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Summary of Amendments 


Summary of Changes 


The “Summary of Changes” section documents changes made to the compiler for this new release. If you 
are a first time user of the Meridian Ada compiler, this section may not be of interest to you. 


If you are were a previous user of Meridian compilers, you will notice some significant changes in the new 
version. The most obvious change being the name. The compiler has been renamed from Meridian AdaVan- 
tage to Meridian Ada. 


The Compiler User's Guide has undergone a complete restructure. It is now broken into two parts with Part 
I, Using the Compiler, documenting how to use the compiler. Part II, Meridian Ada, contains an alphabetical 
listing of all Meridian Ada commands. 


The Installation instructions have been moved to the Getting Started manual. 

‘The following updates and new features have been added to the Meridian Ada compiler for release 4.1: 
e Signed ranges of integers can now be packed. 
© The DOS print screen function can be issued from an executing Ada Program. 
© Validated under ACVC version 1.11. 
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@ PartI Using the Compiler 


This part of the manual gives the concepts behind usi the compiler, basic how to 
use instructions, and then in-depth information for Devel opers and Advanced users. 
The groupings of chapters reflect this organization. Where possible, step by step in- 
structions have been included for performing specific tagks. Tutorials have been in- 
cluded for the compiler and for the debugger. " 
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Chapter 1 Before You Begin _ 
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1.1 About Meridian Ada 


Meridian Ada™ compilers provide fast, efficient, com lete, low priced, oe ion quali Ada program- 
ming capable for fh BM PC™, Apple Maca", DCezton ruent Titan”, Sun 3 and 
Sun 4 computers among others. Contact your sales representative for a complete list of supported hard- 
ware. 


Full generics, tasking, and separate compilation are supported. All standard packages are provided. All of 
the applicable implementation-dependent system programming features (the Reference Manual for the Ada 
Programming Language* ANSI/MIL-STD-1 815A Chapter 13) are implemented. A set of library manage- 
ment tools provides control over programming project organization and of compilation units. Aux- 
iliary directory arrangements permit separation of source code and compiler rated files. 


This User’s Guide covers both the standard DOS version of Meridian Ada and the Extended Mode version. 


The Extended Mode version of Meridian Ada must be purchased separately. The Extended Mode version of 
Meridian Ada allows you to create DOS programs up to 16MB. , 
The compiler comes with the following associated components: 
© The Meridian Ada Debugger, an interactive source-level debugger for use with pro- 
grams written using the Meridian Ada compiler. | 
© The Meridian Ada Utility Library, a set of Ada packages for use with the compiler. 
© The Meridian Ada DOS Environment Library, an Ada component library and pro- 
ductivity enhancing tool. 


e The Meridian Ada Optimizer, a facility that performs a variety of local and global 
optimizations. 


1.2 Road Map for this Manual 


This manual is acombination User’s Guide and Reference Manual. This manual has been divided into sever- 
al sections. 


“Part I Using the Compiler” gives the concepts behind using the compiler, basi¢ how to use instructions, and 
then in-depth information for Developers and Advanced users. 


The Reference portion of the manual, “Part II Meridian Ada Command Reference”, lists all the Meridian 
Ada commands in alphabetical order. 


1.3. What You Should Know 


It is assumed that you are familiar with the Ada language as described in the LRM. If you are not familiar 
with Ada, please refer to the many excellent tutorial and reference works available. 


*The Reference Manual for the Ada Programming Language ANSI/MIL-STD-1815A is more commonly referred 
to as the LRM. To enhance readability, all future references to the Reference Manual for the Ada Programming 
Language (ANSI/MIL-STD-1815A) are shortened to the LRM. 

| 
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It is further assumed that you have some familiarity with the PC-DOS or MS-DOS ™ operating systems, 
including conventions for naming files and invoking programs. You should also have working knowledge 
of a text editor. ; . 


1.4 Integration with ACE 


The Ada Compiler Environment (ACE) is a menu driven, multi-window interface with tightly coupled inte- 
gration to the Meridian Ada compilation system. ACE also contains a powerful text editor with Ada template 
editing capability, an online Language Reference Manual, extensive online help, and interfaces to other Me- 
ridian tools. 

Meridian Adacan be used with ACE or directly from the DOS prompt. This User's Guide describes the com- 
mands as they would be used from the DOS prompt. You will need to refer to this manual for technical details 
about the compiler. Refer to the Meridian ACE User's Guide for instructions on how to use the compiler with 
ACE. 


1.5 Scope of This Document 


This document describes operation of the Meridian Ada compiler, the associated library management facili- 
ties, and implementation dependencies. Both the standard and extended mode versions of Meridian Ada are 
covered in this guide. 

The documentation for the Meridian Ada Utility Library, a supplemental utility library, is included in this 
manual. This is a collection of utility packages that provide access to command line arguments, perform bit 
manipulations and transcendental math functions, and provide more advanced text handling capabilities. 
The Meridian Ada DOS Environment Library is a system interface package that allows you to use DOS sys- 
tem functions, to call BIOS functions, and to perform screen management operations. The Meridian Ada 
DOS Environment Library is documented separately. 
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| 
This chapter provides you with the basic information forusing the compiler. An exercise is included in whi 
you enter a short program and then use the Meridian Ada compiler to compile the program. 


2.1 About the Compilation Process 


Ada Compiler: 
Enter the source code. 
Create program library. 

Compile using the ada command. 


Four basic steps are involved in taking a simple programming project from start tp finish using the Meridian 


-yvny r 


2.2 Creating a Program 


2.2.1 Entering Source Code 


You can enter your program using any editor, provided that editor introduces no i egal characters into the file. 
(Some word processing editors embed control characters or other information is not permitted in Ada 
source code files.) You should enter the program into a file in your current working directory. 

The name of the Ada source code file should have the extension . ada, as in ptg_name. ada. 


Extensions other than . ada are permitted. Refer to section 19.1 for more infotmation. 
2.2.2. Ada Program Guidelines 


The main subprogram must be a parameteriess procedure. In accordance with the Ada language definition*, 
the top level of an Ada program, the main program, must be a subprogram that is a library unit (a top-level, 
non-—nested compilation unit). Do not use a package (even packages that are library units) ora task as the main 
program. 

The bamp command generates the code necessary to elaborate all of the library units associated directly or 
indirectly with the main subprogram. Elaboration of these library units is completed before the code in the 
main subprogram is executed. The bamp command is discussed in sections 2.2.5 and 19.7. 


If it is necessary for a program to obtain information from the execution enviropment, (command line argu- 
ments for example) then a separate package designed for that purpose must be used. Section 18.1 describes 
a package, arg, for precisely that purpose. 


2.2.3 Creating the Program Library 2 


Most programs use standard library units such as package text_io. The pro ) library tells the compiler 
where to look for text_ io which is available in the standard library, paclib\ada. lib. 


*See the LRM § 10.1, paragraph 8 (LRM 10.1/8). | 
| 
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To create a program library that references the standard library database file, use the new1ib command. To 
use new Lib, type new1ib and press ENTER. This creates the program library file, ada. 1ib, and enters 
a link to paclib\ada. lib. 


rare command simply invokes the mk14b command (and a few other commands) with some useful 
defaults. 


The new1ib command should be invoked exactly once in each directory in which Ada compilations are to 

take place. 

Additional details about the library system are given in Chapter 8. 

2.2.4 Invoking the Compiler 

After you have created your program, you will want to compile it. To invoke the compiler, use the ada com- 

mand. From the command line type: 
ada prg_name.ada 


The compiler prints status information to your terminal. This information includes the number of lines com- 
piled and whether or not there were any errors. 

The example shown above is a simple example. The ada command does allow you to request additional ac- 
tions, These actions are requested using command line options. Examples of command line options and their 
actions are -£D, which tells the compiler to generate debugging information and —£E, which generates an 
error file. 


2.2.5 Invoking the Linker 


The function of the linker is to produce an executable program by putting together the separate components 
of the program. 


An example of separate components would be a program which uses the package text_io. Two visible 
components of the program are the package text_io and the program itself. Two invisible components of 
the program that might also be bound in are the Meridian Ada run-time code modules and other library units 
referenced by text_io. 


Given that the various library database files have been properly set up, the linker need only be told the name 
of the main program, as in this example: 


bamp prg_name 


The linker finds all the components of the program, whether visible or invisible, and binds them together to 
produce the executable program. 


2.3 Additional Information 


2.3.1 Running a Program 
To execute the program, simply type in the program name and press ENTER. 
2.3.2 Command Line Options 


line options (sometimes called flags, arguments, switches, parameters, or just options), the Meridian Ada 
commands operate with default assumptions. 
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Some of the more useful and commonly applied command line options involve such things as invoking the 
Meridian Ada Optimizer, requesting more information from library listings or creating compilation listings. 


Command line options are case sensitive; that is, -1 means something different than —%. 


Details of Meridian Ada commands and their options, along with examples, are given in Chapter 19 of this 
manual. 


2.3.3 Kinds of Programs 


There are several kinds of programs that can be created under DOS. The program types that are relevant to 

Meridian Ada are: 

Real Mode Programs The majority of programs that run under DOS are Real Mode programs. Real 

Mode programs run on any DOS system (barring any peculiar system dependen- 

cies, of course). Meridian Ada produces Real Mode programs by default. 

Extended Mode Programs Extended Mode Meridian Ada programs can be njuch larger than Real Mode 
programs (up to 16MB) and can take advantage of extended memory. Extended 
Mode programs can run on DOS systems with 80286 or 80386 processors. 
Chapter 11 discusses Extended Mode programs in detail. This feature is not in- 
cluded in:all versions of the Meridian Ada compiler. 


2.3.4 Reserved Compilation Unit Names | 


| 
A list of library units in the standard distribution library follows. Although it is permitted to use these names 


for your own library units, you should refrain from doing so, because a “Te library unit (one compiled 
in your current working directory) with the same name as a “remote” library unit (such as any of those in the 
standard distribution library) supersedes the remote compilation unit. The compiler prints a warming message 
when this happens. The remote library unit is not destroyed; it only becomes locally inaccessible. This is 
a feature primarily of interest to those who plan to make use of the optional Run-Time Customization Library. 
Package ada_io 

Package calendar 

Package ded_runtime 

Generic Package dizect_io 

Package enum_io_ runtime 

Package file_manage 

Package fio 

Package fixed_io_ runtime 

Package float_io runtime 

Package iio 

Package int io xuntime 

Package io _ exceptions 

Package machine code 

Package num_io rzuntime 

Generic Package sequential_io 

Package syerr | 

Package syio 

Package system 

Package sytime | 

Package task_control 

Package tcd_xuntime | 

Package terminate_runtime 


1 
1 


i 
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Package text_io 
Package tioc_xuntime 


2.4 Helpful Hints 
This section discusses ways to make using Meridian Ada easier. 
2.4.1 Separating Specifications and Bodies 


It is often useful to keep specifications and bodies of packages in separate files. Two commonly used source 
file extensions are: 


ads package specification 

.adb package body 
The primary advantage to keeping package specifications and bodies separate is that if only the body is 
changed, but the specification remains the same, then it is unnecessary to re-compile dependent units. 
When the specification is kept in a separate file from the body, a potentially large amount of time is saved in 
terms of re-compilation and library updating if a change is made to the body that does not affect the specifica- 
tion. 
Whenever a specification is compiled, the library entry for the specification is updated. This causes all units 
depending on that specification to be marked as obsolete, and the units must be re-compiled. If the specifica- 
tion and body are kept in the same file, but only the body is changed, then the specification continues to be 
updated for each compilation, making all dependent units obsolete, and requiring otherwise unnecessary re- 
compilations of those obsolete units. 
Like ordinary package specifications and bodies, generic compilation unit specifications and bodies can ap- 
pear in separate files; however, an instantiation of a generic compilation unit must occur after the compilation 
of the generic’s body. (See Chapter 5 for more information.) 
For more information about the library management system, refer to Chapter 8. 
2.4.2 Reducing Program Size 


One way to reduce program size significantly is to suppress automatic checks by using pragma suppress 
or the -£ flag to the ada command. Programs in which these checks have been suppressed also run much 
faster. Note, however, that suppressing automatic checks sometimes hampers debugging efforts because the 
corresponding “exception never handled” messages are then not printed (see section 3.5). 


Appropriate checks to suppress include: 


access_check length_check 
discriminant_check range_check 
index_check storage_check 


These checks are described in section 11.7 of the LRM. 

Presently, division_check and overflow_check must be suppressed via a compiler flag, -£N; pragma sup— 
press does not work on these two numeric checks. Referto section 19.1 for descriptions of these flags. The 
on => parameter to pragma suppress is presently ignored; a suppressed check applies to all types within 
the scope of the pragma. 

Another way to reduce code size is to omit the -£L flag, also described in section 19.1 Refer to sections 3.5 
and 19.1 for descriptions of the effects of the -£1 flag. . 


2.4.3 Integer Size and Portability 


Programs that must be portable should not rely on the default ranges of values that can be represented by in- 
teger or long_integer objects; instead, explicit integer type definitions (ranges) should be used to de- 
clare such objects: 
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type int8 is range -128 .. 127; | 
— 8-bit integer type 


type uns8 is range 0 .. 255; 
-— 8-bit unsigned type 


type intl6 is range -32_768 .. 32_767; 
——- 16-bit integer type 


type unsl6 is range 0 .. 65_ 535; 
—- 16-bit unsigned type 

type int32 is range —2_147_483_648 .. 2_147_483_647; 
— 32-bit integer type 


Integer size problems usually affect ports of applications from larger systems (c.g. with 32-bit standard inte- 
gers) to smaller systems (e.g. with 16-bit standard integers). 


2.4.4  Catenation (&) and Storage Reclamation | 

When the catenation operator “&:” is used to concatenate two dynamically—sized objects, the compiler must 
allocate temporary space to store the result. The temporaries are reclaimed block boundaries. That is, 
when the statement part of a subprogram, package, task, or block is exited, the for any temporaries 
allocated by the compiler is released. This means that, if temporaries are being in aloop statement, 
memory can be exhausted before the loop is complete. To reclaim the storage sooner, simply enclose the cate- 
nation operation in a block statement as follows: | 


with text_io; 
procedure concat_example is 
begin i 
for i in 1..10_000 loop 
begin 
text_io.put_line("The value is “ & integer’ image (4) ) ; 
—— temporary storage is released here fp tee aes 
end; 
end loop; 
end concat_example; 


i 


In this example, the argument to text_io.put_line causes temporary storage to be allocated for the re- 
sult of the catenation. The begin-end biock surrounding the call causes the temporary storage to be released 
immediately. Without the block, storage_error might be raised at some point when all free memory has 
been consumed by temporaries. 


2.5 Tutorial 


This section shows how to take a small programming project from start to finish using the Meridian Ada com- 
piler and associated facilities. If you have any questions about a specific step, refer to the earlier sections in 
this chapter. 


Note: If you are using ACE, you may prefer to use the tutorials located in the Meridian ACE User's Guide. 


1. Key inthe Ada program shown in Figure 2.1 into a file named fox_demo . ada in your current 
working directory. For more information on entering a program, see section 2.2.1. 
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with ada_io; use ada_io; 
procedure for demo is 


for i in 1..9 loop 
for j in reverse 1..1 loop 
put (3); 


Figure 2.1 Sample Compilation Unit 


2. Create a program library that references the standard library database file by running the program 
newlib. To run newLib, type newl.ib and press ENTER as in the following example: 


newlib 


This creates the program library file, ada. 1ib, and enters a link to paclib\ada.1ib. For 
more information, see section 2.2.3. 


3. Once the program library has been created with the necessary information, the sample program 
can be compiled. For more information, see section 2.2.4. Invoke the compiler with the ada 
command, as in this example: 


ada for_demo.ada 


If the sample program requires no corrections and recompilations, the final step is to invoke the 
Meridian Ada linker, bamp. 


4. To link the components of the program together, use the bamp command as in this example: 
bamp for_demo 


The linker finds all the components of the program, whether visible or invisible, and binds them 
together to produce the executable program. For more information, see section 2.2.5. 


5. The executable program file produced by the linkeris given thename for_demo .exe. Torun 
the executable program file, give the command: 


for_demo 
When compiled, linked, and run, this program produces the following output: 


654321 
7654321 
87654321 
987654321 
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This chapter provides help for some commonly encountered problems. Your first resort should be to read any 
Release Notes that accompany the compiler. These Release Notes sometimes contéin some last minute docu- 
mentation updates. Additionally, the installation chapter located in the Getting Started mamwal, contains in- 


stallation specific troubleshooting. ) 
3.1 Compiler Won’t Run oi 

The compiler won’t run (e.g. it simply returns to the system prompt without doing anything). 
3.1.1 Nothing Happens 


Possible solutions: . 
e Make sure that you have typed an extension (. ada) with the file name to be com- 
piled. , 
e Makesure that path is set correctly (see the installation instructions); type the com- 
mand path to find out. Rebooting the system may cause whatever automatic startup 
procedures that are already in place to set the path correctly. 


e Make sure that there are no resident programs running (print spooler programs, win- 
dow managers, etc.). i 

© Make sure that a “subtle” machine crash has not occurred previously. This should 
not happen, but under some rare circumstances, the compiler may handle program 
errors incorrectly. If this happens, the system is left in an undesirable state. Such 
problems should be reported in writing to Meridian Software Systems with a com- 
plete description of the machine and operating system environment and the circum- 
stances under which the problem occurred. To correct this problem, ‘reboot the sys- 
tem. 


© Make sure that £4.2es=20 in the config. sys file. See the installation chapter 
for more information. 


3.1.2 Cannot Exec 


j 


i 


You receive the error message: 
" eannot exec to path\adal.exe 
This problem usually occurs when, for some reason, there is not enough memory available to execute the com- 
{ 


piler. 
| 


Possible solutions are: | 
e Make sure that there are no resident programs running (print spooleriprograms, win- 
dow managers, etc.). This may include network drivers and y large device 


drivers that consume portions of base memory (the main 640K area). 
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Try rebooting. This may release memory which some previously run editor program 
or other utility continues to hold. 


Ensure that ada . exe actually exists in the path specified in the error message. 
If it doesn’t, it may mean that the compiler was not installed correctly, or that files 
have been moved around or renamed. 


Check your autoexec . bat file to see what programs are invoked whenever your 
system is booted. You should eliminate any invocations of terminate-and-stay—re- 
sident programs (programs that stay around in memory, executing in the back- 
ground). This includes mouse programs, “hot key” programs, and other utilities that 
execute in the background. Once you have modified your autoexec.bat file, 
you must reboot. 


Check your config. sys file to see what drivers are installed whenever your sys- 
tem is booted. If there are many lines beginning with device, then you must elim- 
inate some or all of them. The ans. . sys driver is small enough that it can usually 
remain. Once you have modified your config. sys file, you must reboot. 


If you have more than IMB of memory installed in your system and you have in- 
stalled the Extended Mode compiler, try using that compiler instead. Note: This 
applies only to extended memory, and not expanded (also called LIM) memory. See 
Chapter 11 for a discussion of extended mode versus expanded mode. 


3.2 Compiler Out of Memory 


If the compiler runs 
is used), then compilation 


Ensure that no other resident programs are present. If other applications are in 
memory (e.g. print spoolers, window management systems, spread sheet pro- 
grams,etc.), they should be terminated. The system may have to be rebooted in order 
to clear some applications from memory. 


Use the batch version of the compiler, ada2, described in section 19.2. 


Check your autoexec . bat file to see what programs are invoked whenever your 
system is booted. You should eliminate any invocations of terminate—and—stay—re- 
sident programs (programs that stay around in memory, executing in the back- 
ground). This includes mouse programs, “hotkey” programs, and other utilities that 
execute in the background. Once you have modified your autoexec.bat file, 
you must reboot. 


Check your config. sys file to see what drivers are installed whenever your sys- 
tem is booted. If there are many lines beginning with device, then you must elim- 
inate some orall of them. The ansi . sys driveris small enough that it may usually 
remain. Once you have modified your config. sys file, you-must reboot. 


If you have more than 1MB of memory installed in your system and you have in- 
stalled the Extended Mode compiler, try using that compiler instead. Note: This 
applies only to extended memory, and not expanded (also called LIM) memory. See 
Chapter 11 for a discussion of the difference. 


Reduce the number of symbols that appear in package interfaces. The more symbols 
that appear in the body of a package rather than in the interface, the better. 
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‘5 


Troubleshooting 


When a package is with-ed, all the symbols that appear in its interface consume 
long-term symbol table storage that is not released until the end of the compilation 
unit. : 

e Localize as many symbols as possible The cee Sybil this 
grams and declare blocks, particularly in package bodies, the better. Symbol table 
space consumed by a local symbol is released at the end of the scope in which the 
local symbol appears. This allows the same symbol table space to be reused over 
and over. 


e Split the compilation unit into several smaller compilation units. 
e Split the program into several smaller co-operating programs. This may require use 
of the DOS exec function. The DOS Environment Library provides this capability. 
Note: If bamp similarly runs out of memory, there is a “virtual mode” option for the linker that may help to 
solve this problem. 
3.3 Cannot Find Kernel 


You receive the following error message: 

0S/x86: cannot find operating system kernel 
This error occurs when the Extended Mode MeridianAda compiler was not installed properly. Consult the 
installation chapter in the Getting Started manual for more information. 


3.4 Library Problems 


| 


3.4.1 Main Program Not in Library 


You receive the following error message: 
main program xxx is not in the library ; 
Possible solutions are: 
e Type the 181ib command to find out what exactly is in the library. 
° Make sure that you actually compiled the program in question. 
© Make sure that you did not type an extension (c.g. simple. ada) to the bamp com- 
mand. Be careful not to confuse the file name (simple . ada) with the compilation 
unit name (simple). i 
3.4.2 Missing Library Unit 
You receive the following error message: 
missing library unit x . 
This message appears during compilation when a unit is with-ed that cannot be found in the program library 
or in any of the libraries to which direct links have been established (see Chapter 8). 
Possible solutions are: 
© Make sure that you have used the new14b command in the current directory. A file 
. named ada .14b should be present in the directory if this has been done. 


© Make sure that you have established all necessary links between libraries. Use the 
command 181ib —k to determine exactly which links are present in the program 
library. If the necessary link is missing, it should be added with lnlib. 
{ 
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e Make sure that you have typed the name of the unit correctly in the with clause. 


e Make sure that the unit in question is actually present in the program library or in 
any of the libraries to which direct links have been established. First use the Ls lib 
—k command on the program library and then use the 1s14.b command on each li- 
brary shown in the list of links. 


e Make sure that the unit in question was actually compiled. 
3.4.3 Wrong Version in Library 


You receive the following error message: 
wrong version in library 
This error message appears when mismatched library version number stamps are detected, as when an obso- 
lete library (a library built with a previous release of the compiler) is linked with a newer library. 
Possible solutions are: 


© Make sure that you are using the current version of the newlib program. 


° Make sure that path is set correctly and contains the new Meridian Ada bin direc- 
tory and not the old Meridian Ada bin directory. Type the command path to find 
out. 


° Make sure that no link entries to obsolete libraries are present in your program li- 
brary. Find out what links are present with the ~k option to Ls1ib; get rid of the 
obsolete links with the -r option to Inlib. 


3.5 Exception Never Handled 


When an exception propagates out of the main subprogram, an error is printed at run-time: 


Exception never handled: exception-name 
problem-description in file-name, line line-number 


The problem-description information provides valuable information about how and where an exception was 
raised, simplifying program debugging efforts. Note that the problem-description does not appear unless the 
compiler option -£1 was given (see section 19.1). 


The file-name and line-number information is printed only for exceptions raised in user—written programs. 
The file and line information is not printed for exceptions raised within pre-defined packages such as 
text_io (this is likely to reduce possible confusion about the origin of an exception). 

Only programs that use text_io can produce “Exception never handled” messages for exceptions that 
propagate out of the main program. This means, for example, that programs using package tty from the 
DOS Environment Library for I/O instead of the standard text_io package cannot produce the run-time 
error message. Exceptions may still be handled in the usual way: only the error message is suppressed. If 
any compilation unit anywhere in a program uses text_io-then the “Exception never-handled” message 
can be produced. Programs that use the supplementary packages ada_io, iio, or fio are actually using 
text_4o indirectly, thus such programs can produce the error message. 


3.5.1 Automatic Checks 
For exceptions generated by automatic checks, problem-descriptions include: 
e Assignment would change discriminant 
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e Constraint ‘clash for access type 

e Floating point constraint clash 

© Floating point divide by zero 

e Floating point value out of range 

e Illegal record variant 

e Length clash in multi-dimensional array 

e Length or discriminant clash actual-value /= required~value 
® Reference through null access value 

© Value actual—value out of range first..last 


For value out of range errors, the first and last values of the range are presently printed as integers, even for 
enumerations and fixed—point values. , 

“Exception never handled” messages produced by automatic checks may be suppressed by appropriate use 
of pragma suppress (see section 2.4.2). Note that suppressing automatic checks does not affect any explicit 
raise statements (i.e. an “Exception never handled” pops up if indeed the exception raised is never handled). 


Some pre-defined exception names used by automatic checks are: 


constraint_error storage_error 
numeric_error tasking_error 
program_error 


The meanings of these exceptions are defined in the LRM. 
3.5.2 Storage_Error 


The storage_error exception may be raised, among other reasons, when a local object (an object defined 
inside a procedure, function, or task) is too large. “Too large” here means that the local object cannot be 
accommodated in the available stack space; however, increasing the amount of stack space may not be the 
entire solution. The amount of stack space available at a particular moment varies according to the amount 
of stack space consumed by each subprogram activation. Space consumed by an activation includes the space 
for the parameters and local objects. For example, a local array is going to consume space on the stack when 
the subprogram containing the array is called. That space is reclaimed when the subprogram retums, but if 
the subprogram is called recursively, or many levels of subprogram calls are involved, then the additional 
amount of stack space consumed by each call must be considered. Chapter 13 has some additional informa- 
tion about stack space limitations and how to work around them. 


3.5.33 Other Exceptions 


Anumber of other exceptions used by the I/O run-time packages are defined in package i0_exceptions, 
described in the LRM, section 14.4. 1/0 exceptions include: 


data_error mode_error 
device error name_error 
end_error status_error 
layout_error use_error 


Explanations of the implementation-dependent circumstances under which these I/O exceptions are raised 
are given in this document in Chapter 4. 


Other exceptions can be programmer defined. 


15 Meridian Ada Compiler User’s Guide 


Troubleshooting 


Meridian Ada Compiler User’s Guide 


Chapter 4 Input-Output 
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This chapter provides information onimplementation-dependent aspects of MeridianAda input-output (1/0) 
on PC-DOS. Support packages and generic packages that are affected by implementation—dependencies in 
the I/O are text_io, direct_io, and sequential_io. . 

The low-level run-time I/O support packages use the PC-DOS file system services. Although this chapter 
contains summaries of how this run-time structure affects input-output operations in Ada programs, more 
specific information about the low-level mechanisms is provided in the PC-DOS technical reference docu- 
ments. 


In the PC-DOS configuration of Meridian Ada, extemal files are manifested as sequential files associated 
with devices (e.g. CO8l, PRN, COML) or as sequential and direct files resident on disk devices. 


Ata low level, there is little need to treat PC-DOS files differently based on their contents. For example, files 
containing human-readable text are treated no differently from files containing object code libraries. All disk 
files are treated simply as arrays of bytes (in direct _io) or as byte streams (in sequential_io and 
text _io). 


4.1 Standard Input and Standard_Output 


The files returned by the functions st andard_input and standard_output are associated with the 
PC-DOS standard input and standard output streams. The standard output stream, by default references your 
terminal output device (typically a CRT terminal device named CON). The standard input stream, by default, 
references your keyboard device (also named COW). 


On PC-DOS, the standard input and output streams may be re-directed at program invocation time, as de- 
scribed in the PC-DOS technical documentation. To summarize briefly, re—ditection of the standard I/O 
streams is achieved on the command line by using these special command forms: 


program, | program, _to pipe output to another program 


‘ 
4 


program < file to re—direct input from a file 
program > file to re—direct output to a file 
program >> file to re-direct output and append to the end of an existing file 


Note that it is possible to re-direct output to a device as well; re-directing output to the file named PRN sends 
output to the printer device. 


4.2 Terminal /O 
Terminal input and output is line buffered. That is, input.is not seen by.a progra: \ until a new-—line is entered, 


and output is not visible on the screen until either a new—line is printed or a terminal input operation is per- 
formed (so that same—line prompting works). This means that reading a characte! -at~a—time from the termi- 
nal may not work as expected, since anew-line must be entered by you for the program to see the input. “Raw” 
character input from the terminal can be done via the DOS Environment Library using tty . get in order to 
get immediate character-at~a—time response. 


Greater control over output buffering can be achieved using the Meridian Ada | tility package spi.o. For 
more information see section 18.6. 
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4.3 Opening and Closing Files 


This section discusses implementation-dependencies related to opening files with create and open calls, 
and also closing files with close. 


43.1 File Name Format 


File name strings supplied to the create and open procedures have the forms permitted on PC-DOS. Al- 
though these forms are documented in the PC-DOS technical references, a summary is given here, followed 
by examples. For more information see your DOS User's Guide. 


Briefly, a file name has the format: 

d:path\name.ext 

as in 

c:\ada\test\simple. ada 

where: 

d: The d (disk) portion of a file name is a letter in the range ‘A’..‘Z’ followed by a colon (‘:”). The disk 
may be omitted, in which case the default disk referenced is the currently selected disk, whose letter is 
usually displayed at the commandline. prompt. - 

path \ The path portion of a file name is a directory path specification terminated by a backslash (‘V’). An 
explanation of the hierarchical organization of PC-DOS directories is beyond the scope of this docu- 
ment. Briefly, a directory path specification is a sequence of names (possibly with extensions (.ext)) 
separated by backslash characters. A directory path specification indicates a hierarchically—ordered 
list of directories that must be traversed to find the file whose name follows the path. The path may be 
omitted, in which case the current working directory is used. 

name The name portion of a file name is one to eight characters long, optionally followed by a period (“.”) 
and an extension. Characters legal in names are: 

e The letters ‘A’ through ‘Z’. 

© The decimal digits ‘0’ through ‘9’. 

e The punctuation characters “$&#@!%0-(}”. 

@ The underscore character, *_’. 

© The single quote character, ‘ ”. 

e The accent grave character, * ‘’. 

The lower case letters ‘a’ through ‘z’ are treated as their upper case equivalents. Other characters 
terminate a file name. 


ext The optional ext portion of a file name is one to three characters long, preceded by a period (“.’). 
Restrictions on characters in the name portion of a file name apply also to the extension. The exten- 
sion may be omitted from a file name.-If the extension is omitted, the period may be omitted as well. 
There is no default extension. 

Note the placement of colon (‘:”) and period (‘.”) separators. 

Inside an Ada program, the extension is really considered as just another part of the name, although external 

files are categorized by extensions. Some examples of extensions and the categories represented are: 


.ada, .ads, .adb,. sub 
Meridian Ada source files 
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asm assembly language source files 

-atr interface description (“attribute”) files 

-bat batch command files , 

exe Real Mode executable load modules 

.exp Extended Mode executable load modules 
-gnn generic description files 

.0b3 object files : 
sep subunit (“separate”) environment description 


Some extensions have special meanings to the operating system (€.g. . exe, bat), while others have special 
meanings only to specific application programs (¢.g.. . ada, .atz, .gnn for Meridian Ada). No extension 
is assumed or required by Meridian Ada I/O. S 
Default File Name Components 
Select a disk prior to running a program by specifying its letter followed by a colon, as in this example: 

a: 
A disk may also be selected as the defauit disk from a program by issuing the appropriate PC-DOS system 
call. 
The PC-DOS command ed is used to select the current directory, as in this example: 

ed \ada\test 
The current directory may also be selected from a program by issuing the appropriate PC-DOS system call. 
Note that a separate current directory is maintained for each disk, and the current directory changes when the 
default disk changes. 
Ada system interface functions to call PC-DOS operating system services, such as those that change the de- 
fault disk and directory, are available in the DOS Environment Library. A program need not change its current 
directory or default disk if the necessary selections are made before the program is runorif complete file name 
specifications are given. 
Refer to the PC-DOS technical reference manuals for specific information on operating system commands 
and service functions. : 


Special File Names | 
Note that there are special file names that refer to non-disk devices: 


CON the console 

AUX serial port 1 

COM1 same as AUX 

Com2 = serial port 2 

LPT1 parallel port 1 

PRN same as LPTT 

LPT2 parallel port 2 

LPTS parallelport3 
NUL null (bit—bucket) device 


i 


Non-sequential (direct) input-output cannot be applied to any of these devices. Refer to thePC—DOS techni- 
cal reference manuals for additional information about the characteristics of these devices. Note that there 
may be site-specific reserved device names. 


19 Meridian Ada Compiler User’s Guide 


Input-Output 


To open one of the special files for output, use create with mode out_file (the default mode) as in the fol- 
lowing example: 
with text_io; use text_io; — 
procedure printer_demo is 
£: file _type; 
printer: constant string := “PRN”; 
begin 
create (file => £, name => printer) ; 
—- Open the printer device for output. 
-- Note: assumes that the device is pre-initialized. 
put_line(file => f, item => “This is a test.”); 
new_page (file => f); 
-—- Page eject may or may not be 
— appropriate for any given printer. 
close (file => £); 
end printer_demo; 


This example prints on the printer device the line “This is a test .” followed by a page eject, an ASCII 
FF (form feed) character. Note that although most printers recognize the standard ASCII FF character as the 


page eject, some printers may not:-- ~~ - , 
To open one of the special files for input, use open with mode in_#4.1e as in this example: 


with text_io; use text_io; 
procedure read_com is 
£: file type; 
com: constant string := “COML”; 
line: string(1..256) ; 
last: natural; 
begin 
open(file => f, name => com, mode => in_ file); 
— Open the communications port for input. 
— Note: assumes that device is -pre-initialized 
—— with respect to rate, stop bits, etc. 
while not end_of_file(f) loop 
get_line (file => £, item => line, last => last); 
put line (line (line’ first. .last)); 
end loop; 
close (file => £); 
end read_com; 
This example reads lines from the communications port (under certain idealized conditions) and prints the 
lines on the standard output stream. Note that this example may not work under all circumstances related to 
the communications port. 


File Name Examples 
This section provides some examples of string literals that specify PC-DOS file names. 


o:\bin\£.4ini This is an example of a fully specified path, including drive specifier. It refers to a 
specific file in a specific directory on a specific disk. 


template A filename specified in this form, without directory ordrive specifier, refers to a file 
in the current working directory on the currently selected disk. 
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c:x Because DOS maintains a separate current working directory for each disk, a file 
name specified in this form refers to a file in the current working directory on a spe- 
cific disk. 


4.3.2 File Forms 


File form parameters to create and open must be empty strings (“"). If a file form is notempty, the excep- 
tion use_errox is raised. Note that the default values of file form parameters to create and open are 
in fact empty strings. An example follows. 
with text_io; use text_io; 
procedure file form demo is 
£: file type; 
begin 
_open(form => “”, -— Must be empty or omitted altogether. 
file => f, i 
name => “data”, i 
mode => in file); 
close (file => £); 
end file form demo; 


4.3.3 _ Limitations on Opening Files 


Sharing External Files 
You can have several file objects opened with mode in_file on a single extemal file. 
You cannot have several file objects opened with mode out_file or inout_file on a single external file. 


Number of Open Files 


PC-DOS by default limits the number of open files to 8, including five pre-defined device file associations 
(two of which are used as standard_input and standard_output by Meridian Ada programs). Note 
that this default can be changed at any given site by using the £iles command inthe PC-DOS configuration 
file, config. sys. Remember, no process can have more than 20 files open at one time (including the five 
pre-defined device file associations), and no more than 99 files can be open at one time throughout the system. 
Refer to the PC-DOS technical reference documents for more specific information regarding these limita- 
tions. 


Buffering Considerations 


The effect of opening a device as a file is to cause buffered input or output operations, as with disk files. 1/O 
ona terminal device is line—buffered. Refer to section 4.2 for additional information about the way terminal 
VO works. 


4.3.4 Leaving Files Open 


t 


When a disk file remains open after completion of the main program, it disappears if it was created with an 
empty name (““”). Otherwise, output file buffers are properly flushed and the files closed. Note that a system 
crash leaves output files in an indeterminate state. 

4.3.5 Creating Files 


Files created with create are initially empty, zero—length files. Note that files cannot be created with open. 
Other than described in the previous sections, there are no special considerations for opening files. 
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All files are created with normal attributes: 
e read/write (as opposed to read-only) 
© visible (as opposed to hidden) 
© non-directory (as opposed to directory) 


‘These defaults are acceptable for almost all applications except those few that are system-oriented. Note that 
the DOS Environment Library provides facilities for Meridian Ada programs to get and set specific file attrib- 
utes. 


4.3.6 Closing Files 


There are no special considerations for closing files, except that it is a good idea always to close a file upon 
completing I/O operations on the file. Otherwise, it is possible for a program to run into the limitations on 
the number of open files. Also, it increases the portability of a program; not all Ada implementations handle 
unclosed files upon program termination as gracefully as the Meridian Ada run-time support does. 


4.4 Terminators 


A text_io file terminator is the physical end of a file as defined by the PC-DOS operating system. Al- 
though the Control-Z (ASCII SUB) character is used as a text file terminator, it is discarded on input (i.¢. 
it is not seen by an Ada program). A Control—Z is never written to an output file. 


Aline terminator in text file is a carriage return (Control-M, ASCII CR) character followed by aline feed 
(Control-J (4J), ASCH LF) character. The end of line condition is also set when a file terminator or page 
terminator is encountered. 


A page terminator in a text file is a form-feed (Control-L (4L), ASCII FF) character. The end of page condi- 
tion is also set when a file terminator is encountered. To make the interactive behavior of end_of_page 
sane, there is no wait for a page terminator on terminal input whenend_of_pageis called, but when a page 
terminator is encountered, the necessary processing takes place. 


4.5 Other File Operations 


This section discusses implementation-dependent aspects of other file operations. Exceptions raised by file 
operations are discussed in section 4.7. 


4.5.1 Reset 


Permanent Files 


Any type of permanent file can be reset to any mode. Whenever a permanent text file is reset to out_mode, 
all existing data in the file is destroyed. 


Temporary Files 


The following table indicates under what circumstances the mode of a temporary filemay be reset. The letters 
‘S’, ‘D’, and ‘T’ have these meanings: 
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Ss permitted with sequential files 
D permitted with direct files 
T . _ permitted with text files 


The absence of any letter means that the new reset mode is not permitted with that file type. The word “never” 
ne eaten es ee 


[ss mewresetmode | [ss mewresetmode | 
Ee 
open 
mode ut_file | inout_file 
| _infile | SDT | never | never | 
Lone fo + 


To summarize the table, See ne crmteots agony tect eodein. file. A se- 
quential file of mode out_file can be changed only to anin_file. A direct file of mode out_file or inout_file 
can be changed to any mode. 


4.5.2 Name 


Using the function name with the standard_input and standard_output files retums “STAN- 
DARD_IMPUT” and “STANDARD_OUTPUT™”. 


453 Form 

Function form always retums an empty string (“”). 

4.6 Low Level I/O . 

The pre-defined Ada package low_level_iois not implemented. There are ways to make low-level 
access to system supported devices through facilities in the DOS Environment Library such as abso- 
lute_disk, file_io, port, tty, and video. 

4.7 Exceptions 


There are no special I/O exceptions for PC-DOS. 
Here are the implementation—dependent circumstances under which specific exceptions are raised: 


data_error The data_error exception is raised when there is insufficient data in the file to fill 
up an element of the specified type. 
device_error Device_erzorx is raised for: 


© insufficient memory: The operating system cannot find enough free memory to 
perform an I/O operation. 


e invalid data: Invalid information is read from eerie on which the external 
file resides (as determined by PC-DOS). 


e internal DOS error: Any number of internal errors are discovered by the oper- 
ating system. i 


e illegal deletion: An attempt is made to remove the current directory. 
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name_error The name_error is raised for. 
@ no such file: The file to be opened does not exist. 


© missing file: A file (other than a temporary file) that must exist before being 
opened cannot be found with the specified name or with the specified path. 


e illegal name: The name of the file to be opened is not acceptable to PC-DOS. 


e illegal name: The file name given to open or create is too long (more than 
the maximum numberof characters accepted by DOS-usually 64-or more than 
255 characters, whichever is shorter). 


use_error The use_error exception is raised for: 


e missing temporary file: A temporary file that must exist before being opened or 
deleted cannot be found with the i y-supplied name or with the specified 
path. 


e access denied: The specified file cannot be opened or access to the file is denied 
for some reason. 


@ file system full: The file system cannot accommodate any new files. 
e illegal form: A non-empty form string is given. 


e illegal reset mode: An open file is reset to an illegal new mode (see section 
4.5.1). 


1/0 exceptions are also raised under other circumstances defined by the LRM. 
4.8 WO of Unusual Types 


4.8.1  Unconstrained Objects 


Packages direct_io and sequential_io must only be instantiated on fixed-size objects. I/O of un- 
constrained objects (e.g. strings and unconstrained discriminant records) is not directly supported. Forexam- 
ple: 
-- The Wrong Way: 
with sequential_io; 
package wrong_string_io is new sequential_io (string) ; 
— Error: cannot instantiate with unconstrained type. 


—— One Correct Way: | 
with sequential_io; 
package the_right_way is 
subtype typical_string is string (1. .80); 
package right _string_io is new sequential_io (typical_string) ; 
end the_right_way; 


-- Another Correct Way: 
with text_io; use text_io; 
-- See below. 


Note that although direct_io and sequential_io forthe unconstrained type string, as in the above 
example, is not supported as such, text_io provides all the necessary facilities for input and output of 
strings. 
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As with unconstrained array types (e.g. sting), direct_io and sequential _iocannot be instan- 
tiated for an unconstrained discriminant record type. Note that a discriminant record with default expressions 
for the discriminants is still considered to be unconstrained. Although an instantiation of dizect_io and 
sequential_io on such a record type compiles, a use_error exception is raised at run-time. Also 
note that using a constrained subtype of a discriminant record or using a record altogether without discrimi- 
nants is acceptable. An example follows. 
with direct io; 
package io example is | 
type selector is (iv, cv, bv); 
type vrec(vselect: selector) is 
record 
case vselect is 
when iv => i: integer; 
when cv => c: character; 
when bv => b: Boolean; 
end case; 
end record; 


subtype i_vrec is vrec(vselect => iv); 
subtype c_vrec is vrec(vselect => cv); 
subtype b vrec is vrec(vselect => bv); 


package i _vrec_io is new direct_io (i_vzec) ; 
--This is okay, because i vrec is constrained. 
end io example; 


4.8.2 Access Objects 


Input—output for access types, although permitted, is normally abadidea. An access object previously written 
to a file may be retrieved, but the access object should only be used if the access object is still valid. An access 
object is valid only until completion of the program that allocated the object referenced by the access object, 
or until the object referenced is de~allocated, whichever occurs first. An example follows. 

with direct_io; 

with iio; 

procedure access_io is 

type ip is access integer; 


package ip io is new direct _io(ip) ; 
use ip io; 
i: ip; 
£: file type; 

begin 
create (file => f, name => “icky”); 
i := new integer’ (2); 
write (file => £, item => i); 
set_index (file m> f, to => 1); 
read(file => f, item => i); 
iio.put (i.all); 
close (file => £); 

end access_io; 


This example assigns a value to an integer access object, writes it to a file, retrieves it, and writes the value 
of the object to which it points. Refer to section 17.1 for information about package iio. 
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4.9 Implementation-Defined Types 


In the specification of dixrect_io, the type count is implementation-defined as: 
type count is range 0 .. long_integer’ last - 1; 
In the specification of text_io, the types count and £ield are implementation-defined as: 


type count is range 0 .. integer’ last - 1; 
subtype field is integer range 0 .. dinteger’ last; 
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5.1 Implementation 


In the Meridian Ada compiler, generics are implemented so that they expand fully each time they are instan- 
tiated (this is sometimes called a “macro” implementation of generics). While this implementation of gener- 
ics tends to be very time-efficient, it is not necessarily space-efficient. This means that a generic should be 
written so that as much common code as possible is placed outside the generic unit. Also, a generic should 
be instantiated infrequently to reduce the amount of code generated. Chapter 17 demonstrates some of this 
wisdom as applied to input-output generics. 


5.2 Restrictions 


The specification and body of a generic-compilation unit can appear in different compilation files. This also 
applies to any generic body subunits; however, if this is the case, then any instantiations of such a generic must 
be compiled after the compilation of the generic’s body and any associated subunits. If this order of compila- 
tion is violated, then an error is generated when the Ada program is linked with bamp. The error indicates 
that the compilation unit containing the instantiation is obsolete and must be recompiled. 

The way generics are implemented in Meridian Ada affects certain subtle compilation order requirements 
of the Ada language definition. The compilation unit instantiating a generic depends on the generic’s body 
and any associated subunits, as well as the generic’s specification. This dependency is necessary because the 
validity of the instantiation is determined, in part, by the contents of the generic body. 
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Chapter 6 Tasking | 


This chapter discusses the Meridian Ada implementation of tasking. 


There are two distinct task scheduling methods for Meridian Ada, preemptive and non-preemptive. Normal- 
ly, the task scheduler is non-preemptive (e.g. time slicing is not supported). If the —X option is specified to 
bamp, a different preemptive scheduler is used. Preemptive scheduling allows quicker servicing of interrupts 
on delay timeouts, but has a slight negative effect on program performance in general. 
The priority of a task is fixed at compile-time with pragma priority. The range of priority values is given 
in the integer subtype system.priority (see Appendix F). The default priority is undefined, as in the 
LRM. It so happens that in Meridian Ada taskin; g, a task with an undefined priotity runs at a lower priority 
(a lesser degree of urgency) than any tasks with defined priorities. 
6.1 Non-Preemptive Tasking | a | 
The non-preemptive tasking run-time uses a round-robin prioritized scheduling algorithm that switches 
tasks only at activations, entry calls, completions, and wait conditions. 
In non—preemptive mode, tasks in infinite loops that encounter no tasking constructs inhibit task switching 
altogether. One way to prevent this is to put a delay statement into the loop: 
delay 0.0; 
When a negative delay or a delay of 0.0 is encountered in a task, that task is rescheduled. Any other tasks 
of equal or greater priority will then run first. 
An example: 
with text_io; use text_io; 
procedure reschedule_demo is 
task type customer; 
task type teller is 
entry deposit; 
entry withdraw; 
end teller; 


harried teller: teller; 
hurried_customers: array(1..2) of customer; 


t 
i 
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task body teller is 
customers_remaining: boolean := false; 

begin ; 
put_line(“teller activated”) ; 


accept deposit do 
put_line (“deposit”) ; 
end deposit; 
or 
accept withdraw do 
put_line (“withdraw”) ; 
end withdraw; 
else 
null; 
end select; 
customers_remaining := false; 
for i in hurried_customers’ range loop 
customers_remaining :=— 
customers_remaining or else 
not hurried_customers (i) ’ terminated; 
end loop; 
exit when not customers_remaining; 
end loop; 
put_line ("teller closes window”) ; 
end teller; 


task body customer is 
begin 
put_line ("customer activated”) ; 
harried _teller.deposit; 
delay 0.0; -- reschedule 
harried_teller.withdraw; 
delay 0.0; -- zeschedule 
harried _teller.withdraw; 
put_line(“customer closes account”) ; 
end customer; 
begin 
—— Harried teller & hurried_customer tasks activated here. 
null; 
end reschedule_demo; 


6.2 Preemptive Tasking 


The preemptive tasking run-time supports the following run-time features: 
1. More immediate preemption among tasks of different priorities due to interrupts. 
2. Time slicing among tasks of the same priorities. 


The sections which follow describe preemption and time slicing, the interface to these features, some pro- 
gramming hints for using task preemption and time slicing, and some limitations associated with the current 
implementation. 
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6.2.1 What is Task Preemption? 

Task preemption is the ability to switch from running a lower priority task to a higher priority task as soon 
as the higher priority task becomes “ready to rin”. This task switch might occur at any point in the execution 
of the lower priority task. The higher priority task might become “ready to run” due to the expiration of a delay 
statement, or due to the occurrence of an interrupt for which the task has defined an interrupt entry. 


For example, suppose the higher priority task is waiting for a delay statement to expire. When the last tick 
of the clock occurs that causes the delay to time out, the lower priority task might be in the middle of executing 
the following Ada assignment statement. 

count :# count + 1; 
In fact, the machine instructions generated for this statement might have just loaded the value of count into 
a temporary register and incremented the register by one, but NOT stored the new value back into count 
when the delay expires. Given this situation, task preemption would cause the following to happen, all before 
the value of count is updated. . 

1. The execution of the lower priority task would be suspended. 


2. Thetask'sexecution context (the values inits registers and other task-specific run-time informa- 
tion) would be saved. 

3. The tasking-run—time would restore the execution context of the higher priority task. 

4. Thehigher priority task would resume its execution and continue until ithad to wait again (maybe 
for another delay statement or an entry call). 

5. Eventually, the lower priority task would become the next available task to run. 

6. The lower priority task’s context would be restored and its execution would be allowed to contin- 
ue. Z 


Only now would the updated value of count, which was still stored in a temporary machine register, finally 
be stored into the count variable itself. 
6.2.2 What is Time Slicing? 


Time slicing is the ability to switch between two tasks of equal priority when both tasks are “ready to run”. 
The previous section focused only on the situation where a lower priority task was preempted by a higher 
priority task. This is the minimum degree of preemption dictated by Section 9.8 (Priorities) of the LRM. How- 
ever, the Ada language does not define what should happen when two or more tasks of equal priority are ready 
to run: which one should run first and for how long? The question of which to run first is typically not impor- 
tant but how long it should run is. The LRM does have something to say about how long a task can keep other 
tasks of equal priority from running, but only at what are generally called synchronization points. A synchro- 
nization point is one of the following: ' 


e@ The end of a task’s activation j 
e A point where it causes the activation of another task 
e Anentry call 
e The start or the end of an accept statement 
e A select statement 

e A delay statement 

e Anexception handler 

e An abort statement 
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How long a task can run without reaching these points is undefined by the LRM. 
For example, the current task might be executing the following loop. >) 


loop 
ready := true; 

end loop; 
Such a loop, of course never exits and, in particular, it never reaches a synchronization point. Given the rules 
Sf Ada, even if soch a task is preempted and aborted by a higher priority task, the task need not be terminated 
and need not ever give up control to any task of equal or lower priority. Although this is an extreme example 
of how one task can lock out other tasks from executing, it illustrates a situation which is not uncommon in 
real-life tasking programs. 
To remedy this situation, Meridian Ada preemptive tasking run-time has the capability of performing Sine 
slicing. Time slicing gives you limited control to add a degree of faimess to the task scheduling algorithm s© 
that tecks of equal priority are not forever locked out of running. With time slicing you can dictate the maxi- 
umn amount of time that a given task can execute without giving up control of the processor to other tasks 
of equal priority. 
Note that time slicing only affects the scheduling of tasks of equal priority. The LRM defines when tasks of 
higher or lower priority may run. In particular, in the above example with the loop statement, even if time 
slicing is tumed on, no task of lower priority will ever get a chance to run. 


6.2.3 Using Task Preemption 


For an Ada program to use preemption or time slicing, the program must be linked with the bamp ~I option. 
This option causes the preemptive tasking run-time to be linked into the program. Normally, without this op- 


switches only at synchronization points. This default tasking run-time can be used to generate a program with 
more predictable (repeatable) behavior and slightly less overhead. The default run-time is also compatible, 
in behavior, with previous releases of Meridian Ada. 


The bamp -TI option is only useful if the Ada program actually has tasks in it. 
6.2.4 — Package Task_Control 
When a program linked with bamp =r first starts to run, task preemption is on, but time slicing is off. The 
following sections describe how these features can be controlled by you. 
The following package is part of the Meridian Ada standard distribution library: 
package task_control is 


procedure pre_emption_off ; 
procedure pre_emption_on; 


procedure set_time_slice (quota: duration) ; 
end task_control; 
To improve portability, this package can be used by any Meridian Ada program, regardless of whether it was 
linked with the bamp —I option and regardless of whether it uses tasking. The use of the task_control 
package only affects a program that was linked with the bamp =I option and that does use tasking. 
6.2.5 Controlling Preemption at Run-time 


Recall the task preemption scenario above, where a lower priority task was in the middle of executing the > 
following Ada statement when it was preempted by a higher priority task. 
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count := count +1; 


Note that, if count wasa global variable, itis possible that its value was examinediby the higher priority task 
while the lower priority task was suspended. Ifso, the value of count would have been the value it had before 
the assignment statement was executed. Furthermore, it is possible that the higher priority task modified 
count while the lower priority task was suspended. If this was the case, then the completion of the assign- 
ment statement in the lower priority task would destroy the value of count set by the higher priority task. 
For example, if count was 4 before the assignment statement and the higher priority task set count 10 10, 
then at the completion-of the assignment statement in the. lower priority task count would be 5 and not 11. 
This later case is an example of a program which is formally erroneous as defined by Section 9.11 (Shared 
Variables) of the LRM which makes the behavior of the program unpredictable. Herein lies one of the major 
difficulties in using the task preemption capability correctly; you must diligently protect the use of-shared 
variables (especially those that might be hidden inside some extemal package). 

There are several ways to solve this problem, each with its own costs and benefits. 

One way is to hide a shared resource (such as a global variable) inside the body of a package and provide only 
a procedural interface for accessing the resource. Then have each procedure within the package call on what 
is sometimes referred to as a guard task before accessing the resource to get permission to access the resource 
and call the guard task again after accessing the resource to release the resource for others to use. When proper- 
ly implemented, this scheme should have the effect of allowing only one task at a time to execute the code 
within the package’s procedures. This scheme.is considered to be the standard, approved, way of controlling 
access to a shared resource within an Ada program. 


Another way of controlling access to shared resources is to call the procedures in the task_control pack- 
age to temporarily disable task preemption. While preemption is disabled a task may access any number of 
shared resources without having to worry about another task interfering. Although this is a rather gross way 
of controlling resource access (in that it can affect the execution of all tasks in a program), it requires very 
little overhead in terms of both space and time. 


Preemption is disabled simply by calling procedure pre_emption_off and reenabled by calling proce- 
dure pre_emption_on. These procedures must be properly paired to ensure that preemption is reenabled 
at the right time. Ifnot, then preemption might be reenabled too soon, orit might be disabled for the remaining 
life of the program. Calls to these procedures may be nested as illustrated in the following code fragment. 
begin 
-- Preemption is assumed to be enabled here. 

task_control.pre emption_off; — Preemption is now disabled. 

task_control. pre_emption_ off; -- Preemption is still disabled. 

task_control.pre_emption_on; —— Preemption is still disabled. 


task_control.pre_emption_on; -— Preemption is now reenabled. 
end; 


In general, preemption is disabled whenever the number of calls to pre_emption_off is greater than the 
number of calls to pre_emption_on, although there are two exceptions to this rule. First, calling 
pre_emption_onwhenpreemptionis already enabled does not affect the standing count (that is, it's ano— 
op). Second, if an exception is raised, then the standing count is reset back to the value it had when the block 
that ends up handling the exception was first entered. . 


Note that disabling preemption does not prevent a task from voluntarily giving up control to another task as 
ight occur if it executes a delay statement. For this reason, itis almost certainly a mistake for code to perform 
any tasking operations while it has preemption disabled. 


6.2.6 Controlling Time Slicing at Run-time 


The task_control.set_time_slice procedure is used to tum time slicing on and off and to specify 
the length of a time slice. The length of a time slice is often referred to as the execution time quota which is 
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why the only parameter to this procedure is called quota. Like all duration values, quota, is given in terms 
of seconds. Ifset_time_sliceis called witha quota thatis less than or equal to zero (0.0), then time slic- 
ing is tumed off; otherwise it is tumed on. When enabled, time slicing applies to all tasks of all priorities, but 
remember, it only has an effect when two or more tasks of equal priority are active. 


The amount of time a task gets to execute before its quota runs out, may actually be less than or greater than 
the value given to set_time_ slice for various reasons. Some of these reasons are: 1) operating system 
delays, 2) differences introduced when converting the quota from a duration quantity to the equivalent num- 
ber of system clock ticks (whose duration is defined by system. tick), and, 3) the disabling of task preemp- 
tion. In the later case, if a task’s quota expires while preemption is tumed off, the current task will be suspended 
as soon as preemption is reenabled. In most cases the difference between the specified quota and the actual 
quota will be a small percentage of the specified value. 


Note that the smaller the quota, the greater the amount of overhead added to the program due to the increased 
frequency of task context switching. 


6.2.7 Limitations and Warnings 


The Meridian Ada run-time manages many resources which can be shared among many tasks. Some of these 
include, 1/O resources (files and devices), memory resources (allocating access variables), and CPU resources 
(task scheduling). In order to maintain the integrity of these resources, the run-time code which manages these 
resources is protected from being preempted when preemption is enabled with the bamp -TI option. In par- 
ticular, since the I/O run-time is protected from being preempted, input operations viatext_io’s standard 
input will suspend all other tasks’ execution until the operation is completed. 

When running a preemptive tasking program under the debugger, preemption is always disabled while at the 
debugger’s command level (that is, while the program is suspended at a breakpoint). When the program is 
running, however, preemption behaves as it normally would without the debugger. 


Currently, programs which use the preemptive tasking run-time and are to be run on amachine without a float 
ing point co—processor must be linked with the software floating point library by specifying the bamp —-u 
option at link time, even if the program does not use floating point operations explicitly itself. 


Currently, the full benefits of task preemption are only available to programs running in Real Mode. Programs 
with the preemptive tasking run-time can be created to run in Extended Mode but they will have a lesser de- 
gree of preemption than the same program running in Real Mode. Basically, a task context switch may occur 
in such a program only at synchronization points and at places where task preemption is turned back on by 
the program or the run-time and NOT, in particular, in direct response to an external interrupt, such as might 
occur when a delay times out. 


Since the DOS operating system and its associated BIOS are generally not reentrant, once a request is issued 
to DOS the request must be allowed to complete before another request is issued. With full preemption en- 
abled, it would be possible for a task to gain control of the processor (via a hardware interrupt) while DOS 
was in the middle of handling a request from some other task. If this happens, the preempting task must not 
also issue a DOS request. This can be easily prevented by turning off preemption while a DOS request isin 
progress. As was mentioned before, the standard distribution library and associated run-time does disable 
preemption during such times. However, the DOS Environment Library does NOT currently protect itself, 
so the burden is on the user of this library to do so. In other words, if the application program uses the DOS 
Environment Library with the preemptive tasking run-time, then the program must surround every call to the 
DOS Environment Library with calls to task_control to disable preemption as illustrated in the follow- 
ing example. 


task_control. pre_emption_off; 
error := directory.make ("o: \test.diz”) ; 
task_control. pre_emption_on; 
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6.3 Pragma Shared 


Pragma shared is not necessary because of the way the compiler generates instructions on 80x86 proces- 
sors. Pragma shared is ignored. 


6.4 Interrupt Entries 


Interrupt entries are supported. Atask entry’s address clause can be used to associate the entry with aPC-DOS 
interrupt. Values inthe rangeO .. 255 are meaningful, and represent the interrupts corresponding to those 
values. 


6.5 Memory Requirements 


Each task has a private stack area. This stack area is allocated in the main program control stack (referenced 
by the SP register). In the 80x86 configuration, the total size of the program control stack is presently limited 
to 64K bytes (see Chapter 13). This limit on the total stack space available places an absolute restriction on 
the number of tasks that may be activated in a program. 


Using the default stack all ions in Real Mode, the main program stack space is 20K bytes and the task stack 
space is 20K bytes, for a total of 40K bytes allocated for the entire program stack. In Extended Mode when 
tasking is used, the default stack allocations specify amain program stack of 44K bytes, and task stack space 
of 20K bytes, for a total of 64K bytes. 


Note that no stack space is allocated for tasks when tasking is not used by a program. The total stack space 
allocated to all tasks may be changed by using the —s option to bamp. The total stack size allocated to the 
main program (that stack space allocated for use by everything but tasks) can be changed by using the -M 
option to bamp. 

The amount of stack space required by a task is proportional to the number and sizes of local variables in the 
task and the depth of the task’s call stack. The current individual task stack size defaults to 1024 bytes (1K). 
This places a limitation of about twenty activated tasks in the default stack allocation. The amount of stack 
space allocated for a task can be changed by using a length clause as in this example: 


task type customer; -- See previous example. 
for customer’ storage_size use 512; 
-- Length clause reserves 512 bytes for each 
-- instance of task type customer, as in: 
hurried_customers: array (1..2) of customer; 
-- Each task component of hurried_customers has 
-- 512 bytes of stack space reserved for it. 


In this example, the length clause specifies that half the usual amount of task stack space should be allocated 
for instances of task type customer. 


Naturally, the less space reserved for each task stack, the greater the number of tasks that can be activated. 


Note that implicit run-time support calls as well as explicit subprogram calls must be taken into account in 
deciding how large to make a task stack. 
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Chapter 7 Program Optimization 


7.1 Purpose 


The Meridian Ada Optimizer is an integrated component of the compiler. The Optimizer is used to improve 
the overall quality of the code output by the compiler in terms of both space and time. The Optimizer performs 
both local and global optimizations on your program by analyzing the intemal representation of the program 
output by the compiler. 

The Optimizer is not intended to replace good programming practices. Ie is offén the case that algorithmic 
improvements result in excellent overall performance improvements; however, énly you can understand the 
purpose and use of the program to the extent necessary to implement fundamental changes to the program’ s 
basic algorithms. The Optimizer has no such understanding and can only be used to improve the mapping 
of the program onto the target machine. 


7.2 Operation of the Optimizer ~~ : 
To use the Optimizer, certain command line options are given to the ada and bamp commands. Examples 
are given below. Additional information is provided in sections 19.1 and 19.7. 
1. During the compilation step(s), use the ada ~K option to inform the compiler that the result 
of the compilation may be optimized, as in this example: 
_ ada -K prg_name.ada 
This option causes the compiler to keep information about the compilation available for later use 
by the Optimizer. If this option is not specified for a given compilation unit, then that compilation 
unit will not be optimized. The Optimizer displays a message to that effect during the link step. 
The un-optimized module should be re-compiled using this option. To use the Optimizer to its 
fullest extent, all compilation units in a program should be compiled with the ada -K option. 
Note the capitalization of the -K option. 
Note that extra disk space is required to store the information generated by the compilations. 
2. Once the program has been compiled, the final step is to invoke bamp using one of the optimiza- 
tion options as in this example: 
bamp -G prg_name 
The -G option causes bamp to perform both local and global optimization for the program. To 
perform global optimization only, use the bamp —g option instead. Note that the alphabetic case 
of these options is significant, e.g. -g versus -G. 
When optimization is requested and the bamp verbose option ~v has been specified, information about the 
optimization process is printed during the final link step. If a message is printed that indicates a compilation 
unit has not been optimized but optimization was intended for that compilation unit, then be sure to recompile 
the unit with the ada -K option as discussed above. 


7.3. When to Optimize 


Since extra time is required during the link step to optimize a program, you need to make some decisions about 
development time tradeoffs. During the early and middle phases of a development cycle, it is probably not 
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worthwhile to optimize the program. The tradeoff will generally fall in favor of overall programmer produc- 
tivity, which means that use of the Debugger and faster compile times will be more important than size or 
speed of your program. Once a project is nearing completion, however, itis appropriate to invoke the Optimiz- 
erto begin performance testing and integration. The Optimizer can also provide some information about your 
program that may be of interest, such as names of unused subprograms. 

Note that using the ada -K option does not incur any additional compilation time overhead, although disk 
space overhead is incurred. In terms of compilation time, however, it doesn’t hurt to use the ada -K option 
in preparation for use of the Optimizer. 


7.4 Global Optimization 


Global optimization consists of removing unused subprograms and global data objects from the final extcut- 
able program image. This includes unused runtime code as well as program code. For example, if 
text_io.put_line is called by your program and no other text_ io routines are called, then the re- 
maining run-time routines that are not required are removed from the final program. 


7.5 About .int Files 

The ada -K option preserves a file with the extension _ int foreach library unit. This file is produced by 
the compiler. The file is deleted-after code generation unless the -K option is given. 

An .int file contains the Meridian Intemal Form (MIF) representation of a library unit. MIF is a proprietary 


intermediate program representation generated by Meridian’s Ada, Pascal, and C compilers foruse by Meridi- 
an’s code generators and optimization tools. 


Meridian Ada Compiler User’s Guide 38 


Chapter 8 Library Management 


i 


This chapter describes how the library management system works. An understanding of the details of library 
organization is required only for medium to large scale programming projects. Im most small programming 
projects, nothing more than the new1ib command is required for library management. 
The library system simplifies many aspects of software development by: 
e Enabling the compiler to check interrelationships among compilatioa units, includ- 
ing order of compilation. 2 
e Relating file names and compilation units. 
! 
e Maintaining correspondences between symbol names assigned by the programmer 
and symbol names assigned by the compiler. 
e Keeping track of what object modules to link into a program. 
A software development project can be organized so that compilation units are spread out among several di- 
rectories. Each directory contains a program library that maintains information about the compilation units 
in that directory. A program library (usually just called a library) also contains lihks to other libraries. These 
links simplify library version control and largely eliminate duplication of commonly used compilation units 
such as text_ io. Links among libraries can form complex graph structures, and such structures should be 
organized carefully. Library links are discussed in sections 8.3 and 8.5.1. 


8.1 The Library as a Database 
A program library encompasses many aspects of a database management system. A database is managed by 
several functions: 

e Create and initialize the database. 

e Insert a new object into the database. 

e Delete an object from the database. 

© Modify an object currently in the database. 
The compiler is one component in a code library management system, combining the functions needed to in- 
sert a new object into the database and to modify an object currently in the database. An “object” in this case 
is information about a compilation unit, in particular what its name is and what files are associated with it, 
along with other information. Whenever the compiler processes a compilation unit, either a new program li- 
brary entry is made or an existing entry is modified for that compilation unit. An example of the contents of 
a program library (as listed by using lalib -k) is: 

Links to: 


c: \ada\adautil\ada.1lib 
c: \ada\paclib\ada.lib 

Subprogram file form _demo 
Package io example 
Subprogram reschedule_demo 
Subprogram copy_input_to_output 


j 
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The 1#14b program examines a program library and prints a summary of the contents. This example shows 
links to other libraries and entries for several library units. The library unit entries are produced by compiling 
source files. Library links are discussed in more detail in sections 8.3 and 8.5.1. 
More extensive information about a library and its entries can be produced by using the appropriate 1slib 
options. An example of information maintained in a library about a particular compilation unit (as listed by 
using the —1 option to 1s11b) is: 
Subprogram copy_input_to_output 

Source file name is “copy _inp.ada”. 

Internal link name is “aae”. 

Host system file name is “copy_inp”. 

Can be main program. 

Entered on Tue Apr 14 1987 11:45:51 PST. 

Last changed on Tue Apr 14 1987 11:50:37 PST. 


Dependent on: text_io 
Body is defined. 
Dependent on: text_io 


The remaining database management functions are implemented by separate, complementary tools: 
© The mk1ib command creates and initializes new program libraries. 
© The 1n14b command adds or deletes additional library references (links) to a pro- 


gram library. 
© The rml4b command deletes compilation unit entries from a program library. 
compilation unit 
source file 


it 


inks to 
Meridian Ada Compiler pon-tocal program 


object compilation 
code _ , Unit. 
file information 


Figure 8.1 Compiler/Library Interaction 


The new1ib command simply invokes the mk1ib and 1nlib commands with some useful defaults. Refer 
to Chapter 19 for details about these commands. 


8.2 Compiler/Library Interaction 


The interaction between the compiler and a library is shown in Figure 8.1. When a source file is compiled, 
the library is updated with information about any compilation units or subunits in the source file. In addition, 
the compiler produces object code files and interface description files, the names of which are derived from 
information recorded in the corresponding library entries. If the compiler encounters a context clause (awith 
clause) the library is consulted about the library unit named by the context clause. 
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Consider this compilation unit, a top-level instantiation of a generic package: 


with direct_io; 
package direct_int_io is new direct_io(integer) ; 


When the compiler encounters the with dizect_io clause, the compiler searches the library structure 
for dixect_io, a standard generic package described in the LRM (also see Chapter 4 in this document). 
Under normal circumstances, direct _iois found in the standard library,paclib\ada. lib, adirectlink 
to which must be present in the program library (the library in the current working directory) in order for the 
search to succeed. This link is created as a matter of course by the new1.ib command, which is invoked once 
in each directory in which compilations are to take place. Library links are discussed in more detail in sections 
8.3 and 8.5.1. When the sample package direct_int_io is compiled producing an object code file and 
an interface description file, the compiler updates the program library with information about the compilation 
unit direct _int_io: 
Package direct_int_io 

Source file name is “diio.ada”. 

Internal link name is “aaft”. 

Host system file name is “aaaaaaab”. 

Entered on Tue Apr 14 1987 18:21:03 PST. ; 

Last changed on Tue Apr 14 1987 18:21:03 PST. ; 

No spec initialization 

t on: direct _io | 
Body is defined. 
No body initialization 


The program library keeps track of how up-to-date a particular unit is with respect to others on which it de- 
pends. Forexample, if unit a withs unit b, but then in the course of re-compiling and refining the compilation 
units of the overall program, something is added to or deleted from b’s specification, then unit a must be re- 
compiled. As soon as b is re-compiled with the changed specification, the library entry for a is marked as 
obsolete. : 

Another circumstance under which entries for library units can be marked as obsolete is when a “local” unit 
replaces a “remote” unit with the same name. Forexample, if you were.to write and compile your own version 
of text_io, then any entries for units in the program library that formerly depended on the distribution ver- 
sion of text_io would be marked as obsolete, requiring that they be re-compiled before they can be used 
in other programs. 


8.3 Library Links 


After a program library is created using mk14b, link entries to other program libraries can be given using 
1n14b to make additional compilation units available. This affords the advantage that all compilation units 
need not be compiled in the same directory, thus making it easier to maintain version—-controlled archives of 
tested compilation units. Libraries with standard setups are created with the new1ib command, which sim- 
ply invokes the mk14b and 1nl1ib commands with the appropriate defaults. 


When a context clause (a with clause) is encountered, the compiler searches two levels of the library struc- 
ture: the program library and the libraries to which there are direct links from the program library. In other 
words, the compiler only “sees” those library entries that have been immediately linked with the program li- 
brary, whereas further links and therefore further dependencies are not immediately visible. This scheme is 
directly analogous to the way context clauses work: an entire hierarchy of dependencies is not made immedi- 
ately visible by a single context clause; only those objects visible in the explicitly named compilation unit are 
available. For example, if a withs b, and b withs c, then a can use b directly, but not ¢ (unless a also withs 
c). Amore detailed example is given below. 


41 Meridian Ada Compiler User’s Guide 


Sitch kei he it aa een 
ici at a a aa 
LENE Ne RAAF LON RE RoR rT eT TORT PNET ER er OO ERP nl PO TY ATT 
celearans . ELE NR DTN ARS ee REO Te aR eA mL Ae oR NRO SL EEE RAINS E 
adelaide aniig ins aia 2 
Sc ii a anal 


Library Management 


with c; 
package b is 


end b; 


with b, c; 
procedure a is 


end a; 


package c is 


end c; 
Figure 8.2 Sample Library Units a, b, c 


program. To provide an example of how the compiler’s library search works, refer to Figure 8.2, Figure 8.3, 
Figure 8.4, and Figure 8.5. The latter three figures show different possible library arrangements for three 
compilation units, a, b, and c. Partial definitions for a, b, and c are given in Figure Figure 8.2. Note that 
b also depends on c. To simplify the discourse, it is said that the program library is the library that contains, 
or will contain following compilation, the entry for a. 


local.lib other.lib 


{link to other. lib] 


Subprogram a; 


Figure 8.3 b and c Immediately Available to a 
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{link to other.lib} - 
[link to another. lib] 


Figure 8.4 b and c Immediately Available to a | 


local.lib other.lib 
[link to other.lib] | [link to another.lib} . 
Package b; | 


another.lib 


Figure 8.5 c Not Immediately Available to a 


In the library arrangement shown in Figure 8.3, both and c have entries in the game library, and this library 
is referenced by a link entry in the program library. This makes it possible to specify context clauses for both 
b and c in the compilation of a. 


In the arrangement shown in Figure 8.4, entries for b and c exist in separate libraries, and both libraries are 
referenced by link entries in the program library. Again, this makes it possible to specify context clauses for 
both b and c in a. 


In the arrangement shown in Figure 8.5, entries for b and c exist in separate libraries, but only the library 
containing the entry forb is referenced by a link entry in the program library. ugh there is a further link 
entry in the library containing the entry for b to the library containing the for c, this is insufficient to 
make c available to a: the compiler reports an error in attempting to find the information it needs for the com- 
pilation unit c. : 
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8.4 Auxiliary Directories 
When a source file is compiled, a number of associated files are created depending on what kind of compila- 
tion units are involved. For each compilation unit, the associated files may include: 

° an object code file (. ob3) or an assembly language code file (. asm) 

e an interface description file (. atx) 

e generic description files ( .gnn) 

e subunit environment description files (. sep) 


Figure 8.6 Auxiliary Directory Arrangement 


Since you usually never need to deal directly with the associated files, it can be inconvenient or unsightly to 
keep these files in the same directory with the source files. The library system supports auxiliary directories 
in which the various files associated with a particular library’s compilation units are kept. This kind of ar- 
rangement is shown in Figure 8.6. Without an auxiliary directory, all associated files are kept in the same 
directory in which the compilation takes place. 

The newlib command builds an auxiliary directory by default. If the mk1ib command is used in place 
of the new1.ib command, then an auxiliary directory, if one is desired, must be specified with the —a option 
to the mkLib command. The mk1ib command does not automatically create the auxiliary directory; it must 
be created with the PC-DOS mkdiz command prior to the first compilation involving the library. Refer 
to the details of the mk14b command for more information. 


8.5 Special Considerations 


This section discusses some of the idios: ies of the Meridian Ada library management system. You 
should be aware of these aspects so that recovery from certain unusual error conditions is made easier. 


8.5.1 Unique Names and Library Links 


Because the lengths of programmer defined Ada identifiers may exceed limitations for file names and linker 
symbol names, somewhat shorter, unique abbreviations or “artifi ial” names are generated and name map- 
pings recorded in the library. 

The unique file name mappings used to prevent collisions among similarly named library units are coordi- 
nated among libraries that are linked together. ‘These mappings are not coordinated among disjoint libraries. 
Thishas several implications. First, this means that inmost cases, multiple program libraries should not coex- 
ist in the same directory because of file name collisions. It is possible to maintain co-resident program li- 
braries, each library with its own auxiliary directory. This permits any number of program libraries to be co— 
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resident, To maintain such an arrangement, more work is required than simply using a single program library 
with the default name in each directory, since the non-default library must then be named explicitly with each 
library management command (including compilation). Auxiliary directories are discussed in section 8.4. 


Next, you must be aware that certain library arrangements pose interesting problems when the time comes 
to merge sections of separately maintained program development efforts. Some arrangements prevent the li- 
brary system from properly maintaining unique names across a set of compilation units. Consider the arrange- 
ment shown in Figure 8.7. The disjoint libraries X, Y, and Z all have link entries for the library A. Unique 
name mappings are not coordinated among X, Y, and Z, although the mappings are coordinated between A 
and any of the individual libraries. Note that the lack of coordination among X, Y, and Z only poses a problem 
if modules in X, Y, and Z are ultimately linked together. 


| 

Figure 8.7 Disjoint Libraries i 

In Figure 8.8, another problematic arrangement is shown. in ae cate ee ea 
between libraries A and B, creating possible complications for compilation units that use library Z. Note that 
the lack of coordination between A and B is not a problem if both libraries are“ zen”. 


Figure 8.8 Another Disjoint Library Arrangement 
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One possible way around such problems is to make additional library links, provided that the links are acyclic, 
as shown in Figure 8.9. 


Figure 8.9 Fully Connected Library Structure 


An important point for programming project library management is that in any given subtree of a library 
graph, the libraries lower in the tree should be changed relatively infrequently. In Figure 8.7, library A should 
be changed as little as possible, iflibraries X, Y, and Z are the libraries for the main code development efforts. 


8.5.2 Library Integrity 


Terminal-originated interrupts (Control-C (“C)) are disabled during the short periods that library updates 
are in progress. This is to prevent possible corruptions of library contents. 


The library management tools provide ways to handle the associated files automatically, but some planning 
is required when deleting or moving files. If files are to be moved or deleted, the rm1ib program should 
be used to update the library. Some recompilations may be necessary as well. 


The rmlib command removes entries from a program library. Source files are left intact, but associated 
files are deleted. Since an individual library entry may be part of a complex dependency graph, a number of 
other related library entries may have to be deleted first to maintain the integrity of the graph. If a unit is re- 
moved from a library, other units that depend on the deleted unit cannot be compiled. 


In the unlikely event that a library database file becomes corrupt (usually because a library update was 
somehow aborted in midstream) it may be necessary to delete the program library. The library must then be 
reconstructed from scratch and the entries restored by recompiling all the source files in the directory. Of 
course, if an archival backup copy of the program library is available, then only the units modified since the 
backup operation need be compiled once the file is restored. 
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The Meridian Ada Software Floating Point Run-Time (SFPRT) permits an Meridian Ada program to runon 
systems without an 80x87 math co-processor (an 8087, 80287, or 80387), but takes full advantage of a math 
co-processor if installed. The information in this section applies only to those programs containing floating 
point computations. Programs that use only fixed point or integer computations are not affected. 

To ensure that programs operate safely on any system, a missing math co-processor causes a 
program_error exception to be raised with the message “must install, math coprocessor 
to use float operations” unless SFPRT is used. SFPRT is linked wi a program whenever the 
bamp —u option is used. To ensure that a program containing floating point ions will run on all systems 
regardless of the presence or absence of a math co-processor, the program should be linked with the bamp 
—u option. 

To permit programs to run more quickly on systems with math co-processors, the compiler always generates 
80x87 instructions for floating point operations. SFPRT, if used, interprets the 80x87 instructions. SFPRT 
is used only if no 80x87 is present. If present, the math co-processor is always used for floating point opera- 
tions, regardless of whether or not a program is linked with SFPRT. 


By default, a call to a special routine is placed before each sequence of floating point instructions in the gener- 
ated machine code. The special routine takes action based on whether or not a math co—processor is installed 
and whether or not the floating point software is present. If there is no math co—processor available, the routine 
either raises the program_error exception or uses SFPRT, if SFPRT was linked into the program. The 
ada —£¥ option suppresses this call. This makes a program smaller and faster, but by using this option, the 
programmer “guarantees” that the program so compiled will never be used on a system without a math co— 
processor, since the normal checks are eliminated and SFPRT then cannot be used. If a program compiled 
with -£¥ is run ona machine with no math co—processor, the machine may simply “freeze up” in this circum- 
stance, requiring a reboot. 


The ada —£¥F option and the bamp -u option should not be used in the same program; it is pointless to 
link SFPRT into a program when all calls to SFPRT have been suppressed by -£F. 


The following table summarizes the various combinations of options and their effects on program execution 
depending on whether or not an 80x87 math co—-processor is present in a particular machine. The cases where 
SFPRT is available are emphasized, since this is the most robust program configuration. 


Program fails; behavior unpredictable; 
checks for rno . 
SFPRT available 
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Note: There are some very minor differences in precision between results computed by SFPRT and the 80x87 
math co—processor. These differences are most noticeable in the results of transcendental functions from 
package math_14b in the Meridian Ada Utility Library, although the differences are still small. 
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10.1 Introduction 


The Meridian Ada Debugger is an interactive source-level debugger for use with programs written using the 
Meridian Ada compiler. The Debugger allows you to debug in high-level Ada terms; no knowledge of the 
underlying machine architecture is required. A debugger command can be an Ada variable expression to be 
printed, an Ada assignment statement, or an Ada subprogram call (including Debugger subprogram calls). 
The Debugger possesses an identifier completion facility, acommand history mechanism, acommand editing 
facility, and a help facility. The Meridian Ada Debugger can greatly improve productivity. 


10.1.1 Overview of Debugger Facilities 


The Meridian Ada Debugger commanid processor provides these facilities: 
e simple commands with Ada syntax 
© one-key identifier completion 
© command history and editing 
© on-line help 
Debugger facilities for control of execution include the following features: 
source line breakpoints 
single stepping 
variable “watches” 
automatic exception breakpoint 
task breakpoints 
Debugger “at” commands 
The program state can be examined in several ways: 
@ source code review 
© object display | 
© subprogram call back trace 
© active execution tracing 
The program state can be modified at breakpoints with: 
e variable assignments 
© user subprogram calls 
10.1.2 Source—Level versus Machine-Level 


The Meridian Ada Debugger deals with programs in high-level Ada terms; no knowledge of the underlying 
machine architecture is required. In a traditional machine—level Debugger, you must be intimately familiar 
with the compiler, because you must set breakpoints on machine instructions, and values of variables are de- 
termined by dumping regions of memory. With the Meridian Ada Debugger, you set breakpoints on Ada 
statements, not the underlying machine code instructions, and the value of a variable or component can be 
easily printed using a format suitable for its type. 
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10.2 Debugger Tutorial 
This tutorial introduces you to some of the features of the debugger. The program, dbtest, used during 
snis exercise is located in the test directory where you installed the compiler. 
Commands are executed by pressing ENTER®. For example, you would type the command and then press 
ENTER to execute. This instruction has been omitted from each stepin order to avoid repetition and improve 
readability. 
If you are using ACE, you can perform the debugger tutorial located in the Meridian ACE User's Guide. 
if at any time you want to exit the debug session, type quit at the prompt (>). 
1. Change to the test directory located in the directory where you installed the comPler 
2. if you have not already created a Meridian Ada brary, do so now using the new» commans. 
newlib | . 
3. Compile the program, dbtest. To prepare the program for debugging, use the -£D option. 
ada -£D dbtest.ada 
4, Link the program using bamp. 
bamp dbtest 
The program has now been compiled and linked with debugging enabled. 


5. Execute the program by typing the program name, dbtest. The program begins execution in 
the debugger, suspended at the start of the main program. 


dbtest 

6. To get a listing of debugger commands, type help. 
help 
A listing of the available debugger commands is shown. 


7. Toprinta listing of all local variables and their values use the dumpal1 command as shown be- 
low: 


dumpall 


The first line contains the subprogram name (dbtest) and the line at which the program was 
suspended (1). The values of all global variables in all units are displayed. 


8. You can also examine the variables and their value by naming them directly. To display the value 
of the variable x, type the variable name at the prompt as in this example: 


x 
The current value of x is 0. 
Now display the value of a by typing the variable name @ at the prompt: 
7 
The current value of ais (RED. .BLUE => 0). 

9. To set a breakpoint on line 21 of dbtest, use the following command: 
breakp (dbtest, 21) 


2 
This is also called the Return key on some systems. 
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Set breakpoints at lines 22 and 23. 

breakp (dbtest , 22) 

breakp (dbtest , 23) 

To see the breakpoints, use the List command: 
list 


The command displays the program name and the line number where 'the breakpoints occur. The 
List command also indicates that there are no watches or traces in effect. 


Issue the ss command. The ss command means “single step” through the program. The ss 
command also single steps into any calls. 


ss 
This executes to the first breakpoint. 


If you now execute a dumpal.1 command, you will be able to see how the program has executed 
through the initializations and how the variables were updated. 


dumpall 


If you want to monitor a particular variable, use the watch command. For example, to monitor 
the variable t, enter the following command: 


watch (t) 


Do alist command. Now you can see that the variable t has been added to the list under the 
watches section. The watch command monitors the stated variable (in this case, variable t) 
during execution, suspends the program, and displays the original value and current value when 
the variable is changed. 


list 


Execute the program until t is changed by using the ¢ (continue) command. The c command 
executes to the next set breakpoint. 


c 


Information about the watched variable, t, is displayed along with ana about the next 
breakpoint. 

To cancel the watch on variable t, issue an unwatch command as shown below: 

unwatch (t) 


To see your position during the execution of a program you can use the where command. Enter 
the where command now. 


4 


| 


' where 


18. 


19. 


The where command displays a listing of the current source statement including 5 lines before 
and 5 line after. The current line is denoted with an asterisk (*). _, 


The trace command allows you to trace subprograms. To trace all subprograms, use the tra- 
ceall command. 


traceall 


The traceall command traces through all subprograms. If you only want to trace through one sub- 
program use the trace (subp) command, substituting the subprogram in parentheses. 


You can continue execution of the program using the continue command as shown below: 


a 
} 
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sThe output displays the call to procedure p, the calling value, the remming value of P, and Proo®- 
dure p retuming. 


20. To tum off a trace, use the untraceal1 command 
untraceall 
21. To continue through the program, issue another o(ontinue) command. 
c 
‘This should take you to the end of the program and the following messages are displayed: 
wxys 
Program terminates normally. 
22. To exit the debugger, use the quit command. 
10.3 Preparing Code to be Debugged 
The Debuggerisnot a separate program; instead, the debugger s linked directly into a WSS Progra Compila- 
tion units to be debugged are compiled swith-the- debugging flag -£D as in this example: 
ada -£D test .ada 
bamp test 
When a program compiled in this way is inked and executed, the Meridian Ada Debugger! automatically 
invoked. 
For compilation units compiled with debugging enabled, the compiler generates special debugging code with 
the compiled code. The debugging code makes calls to debugger library routines at strategic points, usually 
after every source statement line. The debugger library routines monitor execution of code within the de- 
bugged units. Any or all of the units in a program can be compiled with the debugging flag, although itis rec- 


ommended that the main subprogram always be compiled for debugging. Those units compiled without de- 
bugging are inaccessible from the debugger. When bamp is run, the debugging run-time support is 
automatically linked into the program. 


This code-insertion method allows for an extremely powerful debugger that can interact with your program 
to a high degree, but it does incur some additional overhead. Programs compiled in Debug mode tend to be 
somewhat larger and slower than those compiled normally. 


Meridian Ada Debugger commands have several forms: 
e an Ada variable reference 
e an assignment 
e auser subprogram call 
e a Debugger call 
These command forms are explained in the following sections. 
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If you have named a local variable using the same name as a debugger command, then typing the command 
displays the value of the variable. This means that the debugger command does not execute. To execute the 
debugger command instead of displaying the variable value, type: 

debug. [command_name] 
10.4.1 Ada Variable References 


The value of any Ada object can be printed by simply typing the name of the object. If a simple object name 
is typed, the entire object is printed in a format appropriate for its type; numeric types as numbers, enumeration 
types as enumeration identifiers, strings as string literals, and arrays or records, of any combination thereof, 
as properly indented aggregates. Components of composite types can be printed by specifying the corre- 
sponding Ada name. The name can include array indexing or slicing, record component selection, . a1 se- 
lection for access types, and Ada attributes: ‘ first, ‘ last, ‘length, ’ constrained, ’ address, 
or ‘ size. Examples are given below. Many other Debuggers have more complicated syntax for examining 
values at machine addresses, and permit only one level of indirection. The Meridian Ada Debugger has no 
Simple Objects 
Simple objects are printed according to their underlying types as in this example: 

x: integer := 12; 

c: character := ‘T’; 

b: Boolean := false; 
These objects are printed simply by entering their names: 

>x 

12 

>s 

s rr 

>b 

FALSE 
Array Objects 
Consider these source declarations: 

type color is (red, yellow, blue); 

a: array(color) of integer := (2, 3, 5); 

t: string(3..6) :2 “wxyz”; 

type rec is 

record 
x,y,z: integer; 
end record; 

ze: array(1..3) of rec := ((11,12,13), (21,22,23), (31,32,33)); 

type ptr is access rec; 

Pp: ptr := new rec’ (xr(2)); 
When an array object name is typed, the array is printed as an aggregate using named notation: 

>a 

(RED => 2, YELLOW => 3, BLUE => 5) 
The array can be indexed or sliced as in Ada: 

> a(yellow. .blue) 

(YELLOW => 3, BLUE => 5) 

> a(yellow) 

3 
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Arrays of type string are printed specially: 
>t . 2) 
“ways” : : 
> t(4..5) 
“xy” 
>t (6) 
fg’ 
Array attributes can be used as in Ada: 
> a’ fizst 
RED 
> a’ last 


BLUE 

> a’ length 
3 

> t’ first 
3 

> t’last 


6 
> t’ length 
4 
Indexes and slices can use attributes as with normal Ada syntax: 
> t(a’ length) 
e w’ 
> ¢(4. .5)’ length 
2 Sy 
Record Objects 
Record objects are also printed asnamed aggregates. Complicated nested structures are printed in an indented, 
readable format: 
>rz 


( 

1 => (x => 11, y => 12, 2 => 13), 
2 => (x => 21, y => 22, z => 23), 
3 => (x => 31, y => 32, = => 33) ) 
> r(2) 

(x => 21, y => 22, 2 => 23) 


Access Objects 
The value of an access object is printed as an address in hexadecimal. The referenced object can be printed 
using Ada’s . all construct: 


>P 
[ 4¥FE : 49E6] 


i Le a) 


21 
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A pointer value consists of a 16-bit paragraph address and.a 16~bit offset in Real Mode programs. A pointer 
value consists of a 16-bit segment selector and 16-bit offset in Extended Mode, 


In most instances, a pointer value is examined only to see if it matches a second value. Its actual value is of 
no interest. ; 

Refer to the Intel 80x86 literature for details about the machine-level addressing methods. 

10.4.2 Output Formats 


The following table summarizes the printing methods used for various Ada types: 


[ier integerinen 
[—tioat [exponential reatnottion | 
[fied [real with conect precision —__| 
a ao 


integer i 

float 

sing | 
[ray s[amayageeeme 
hex address value 


10.4.3 Subprogram Calls | 


Subprograms defined by you can be called directly from the Debugger. All necessary parameters must be pro- 
vided. The retum results of functions are printed according to their return value types. Subprogram calls and 
variable references are subject to visibility constraints (discussed in Section 10.13). Currently, only positional 
parameters are supported; named parameter notation cannot be used, and all default parameters must be speci- 
fied explicitly. Debugger commands are simply built-in subprograms that can be called just like user subpro- 
grams, but some Debugger commands are treated specially in that they accept a variable number of parame- 
ters. All built-in Debugger subprograms are summarized in Section 10.16. 


The calling facility allows you to test program components interactively, easily, arid thoroughly without writ- 
ing tedious test programs. It is also useful for displaying complex data structures such as trees or linked lists. 
You can define printing routines that can be called as needed from the Debugger. 


Consider the following simple table lookup package: 
package table is 
type element is 


record 
key: integer; 
value: character; 
end; 
Re procedure enter(key: integer; value: character) ; 
a function lookup (key: integer) return character; 
end table; 
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suppose the body ofthis pickage allocates an eLement record whenever ent.ex i called. The Snciion 
Lookup retums the entered value, if found, and ’ *’ otherwise. 
cnce tis package is compiled and linked with an empty main program, itcan be easily tested using 106 ier 
active call facility of the Debugger: 

> lookup (5) 

ee 

> enter(3, ‘a’) 

> enter(5, 'b’) 


An in parameter to a subprogram call in a Debugger command can be any legal Debugger expression. As al- 
ways, only variable references can be given for out or in out parameters. Parameter lists (where required) are 
ve ye as in Ada source code:enclosed in parentheses; each parameter separated from any others Dy commas, 
Subprograms that have side effects will, when called from the Debugger, have the same side effects 0 TY 
would have under normal run time conditions (e.g. dispense_money, read_next_xecord, 
launch_missile). Some caution is required when calling such subprograms in the Debugger. 


10.4.4 Assignments 


Assignments to variables are permitted using the normal Ada assignment notation, “: =”, Any variable refer- 
ence is permitted on both the left and right sides of an assignment: 


> t(5) 3:2 ‘A’; 


> e(4) := (5); 


Expressions in assignments can be variable references (as above), any function call, scalar constants (e.g. 
3.14159, 512, true), or quoted character literals (e.g. ‘c’). Aggregates and multipart expressions (using infix 
unary or binary operators such as “+”, *-”, ornot) cannot be used in Debugger assignment commands at 
present. 


Some type checking is performed, but it is not as rigorous as the compiler’s. Note that a semicolon (‘*;”) at 
the end of an assignment is optional. Itis not possible to set the value of apacked record field ora packed array 
element using Debugger assignments. 
Consider these source declarations: 

type color is (xed, yellow, blue) ; 

£, g: float; 

hue: color; 

b: boolean; 

ec: character; 
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Some examples of Debugger assignment commands using these variables are: - 

£ := 3.14159; Simple assignment to a float variable, £. ) 

g :* sin(f); Call to user-defined function sin; value assigned to a float variable g. 
hue := blue; Simple assignment to an enumeration variable, hue. 

b :# odd(4); Call to user-defined function odd; assignment to a boolean variable, b. 
Gsm '2Z'; Assignment to a character variable, c. | 


10.4.5 Debugger Calls 


The Debugger contains many commands — actually specially defined subprograms — that can be called to dis- 
play or modify the debugged program and the debugging environment. For example, the procedure stack 
can be called to print a stack trace, and the special procedure breakp can be called to set a breakpoint. These 
special subprograms are described in detail in the sections that follow. The commands are summarized in Sec- 
tion 10.16. 


10.5 Displaying the Environment , 
Several debugger procedures—commands—are pre-defined for displaying information about the program 
being debugged. 


10.5.1 Printing Source Code 


The Ada source code can be displayed without having to specify a source file or line number. A summary of 
the source code display commands to the Meridian Ada Debugger follows. A ome description of each 
command appears in section 10.16. 


print When the Debuggerprint command is invoked with an Ada subprogram as its argument, a 
portion of the subprogram is displayed. Relative line numbers (starting at 1) are displayed 
with the source so that locations for desired breakpoints can be specified. The print com- 


mand prints 10 lines. 
more The more command can be used to print subsequent sets of 10 lines. 
find The £ind command can be used to search the current procedure fora particular text pattern. 


source The source command can be used to specify an alternate directory in which source files are 
to be found. Normally the current directory is used. 
where When a breakpoint occurs, the current source line is displayed. The where command prints 
a smail section of the source code centered about the line where execution is currently sus- 
i 
10.5.2 Displaying the Call Stack 


The stack command can be used to print the call stack. Each call that hasn’t yet retumed is printed, starting 
with the most recent one- The calls are printed as Ada calls using named parameter notation to specify the 
parameter values. For each call, the relative line number in the caller from which the call occurred is printed. 
A complete description of the st ack command appears in section 10.16. 


10.5.3 Dumping Variable Values 


The dump command can be used to print all of the variables for a given subprogram or package, allowing 
you to look over the current state of the environment. The dumpal1 command dumps every variable in the 
entire program. A complete description of the dump commands appear in section 10.16. 
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10.6 Control of Execution 


hen a breakpoint is encountered during program execution, the program is suspended and tie CcvegEr 
Meee enrrezsoris invoked. Breakpoints normally occur automatically atthe beginning and end of Pro 
gram execution; these automatic breakpoints can be suppressed with the silence command. 


Commands related to breakpoints follow. A.complete description of each command appears in section 10.16. 


silence The ei.lence command suppresses the automatic breakpoints at the beginning and end of 
program execution. This command is normally placed in the debugger initialization file. 


breakp A breakpoint can be set on any Ada statement by specifying a subprogram and relative Tine 
command. 


number with the breakp 
c To resume the program from a breakpoint, use the “continue” command, c. 
ss The “single-step” command, as, can be used to execute a single statement before returning 
to the debugger command level. 


10.6.1 Setting Breakpoints 


gram) as its second parameter. if the line number is missing, the breakpointis set at the start of the subprogram. 
Relative line numbers are displayed when a subprogram is printed using the print command. The special 
line number —1 refers to the end of the subprogram. 


10.6.2 Resuming Execution 
At a breakpoint, there are several ways to resume execution. The simplest is the continue command, ce. This 
causes the program to resume ex! ion until another breakpoint is encountered, or until termination. 


The single-step command ss causes the program to execute a single statement before retuming to the debug- 
ger. If the current statement contains a call, the single-step command causes a breakpoint to occur at the start 
of the called subprogram. 


The gocommand continues to the next statement within the current subprogram (calls are skipped over). Mul- 
tiple statements on a single line count as one go step, as in this example: 


a:2 7; b := 3; 
ter is vryen execution proceeds until either one ofthe specified lines is reached. This can be useiu 901 


A breakpoint can be removed by using the unbreakp command with the same parameter sequence as the 
breakp command. The List command can be used to see what: breakpoints.are currently set. 


10.6.3 Watching Variables 
A “watch” can be set on a variable, causing a breakpoint to occur after any statement that modifies the value 


of the variable. This can be especially useful in tracking down subtie bugs where vatiables are changing unex- 
pectedly. The watch command takes a variable name as its parameter. 


For example, consider the following program: 
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If you set a watch on the variable n, and then continue execution, a breakpoint occurs when the value of n 
changes: 


> watch (n) 

>ec 

variable n has changed 

old value was 37 

new value is 73 

Breakpoint at line 5 in p (line 6 in watch.ada) 
20* on :s 73; 

> 


The breakpoint message prints old and new values of the watched variable and the line where the change oc- 
curred. The relative line number within the procedure and the absolute line number in the source file are 
printed. 


The unwatch command removes a watch. A watch must be removed on a local variable before the enclosing 
procedure exits, and a watch on an allocated object must be removed before the object is deallocated. The 
1ist command displays the current watches. 


10.7 Monitoring Execution 


This section describes methods for monitoring execution of the program being debugged. The trace com- 
mands can be used to cause the debugger to output the call and retum structure of the program, and the at 
command can be used to cause a specified action to occur whenever a particular line is executed. 


f 


10.7.1 Subprogram Tracing 


Subprograms can be traced by using the trace or traceal1 commands. When a traced subprogram is 
called, the debugger writes out the name of the subprogram, and the names and values of its parameters. The 
tzace command tums on tracing for a specific subprogram as in this example:. 


> trace (lookup) 


Given this example command, whenever the user-defined subprogram lookup is called during program 
execution, the call is printed as an Ada call with named parameters. When the subprogram retums, the retum 
value (if it is a function) is printed. The information is indented as the calls nest more deeply, and the indenta- 
tion is properly maintained when exceptions disrupt the normal call and return structure of a program. The 
txaceall command can be used to trace every subprogram in the program. 


with ada_io; use ada_io; 


| 
procedure factorial is 
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function fact (n: integer) return integer is 
begin 

ifn < 2 then 

return 1; 

else 

return n * fact(n — 1); 

end if; 

end; 


procedure do_fact (x: integer) is 
£: integer; 
begin 
£ := fact (x); 
put (“fact (”); 
put (x); 
put (“) =”); 
put (£); 
new_line; 
end; 


ro are 
do_fact (3) ; 
end; 


Anexample of a debugger session using the traceall command with the above program is shown below. 


" fact (n=> 1) 
fact returning 1 
fact returning 2 
fact returning 6 
fact (3) = 6 
do_ fact returning 
Program terminates normally. 
> quit 


Parameters and function return values are printed using Ada cbjecttype infomation. The unt race and un- 
traceall commands are used to remove traces. The List command prints the current traces. 


10.7.2 Inserting Commands 


Debugger commands can be inserted into the code so that they execute each time a particular point in the code 
is reached. The at. command specifies a subprogram and relative line number, and the command to be ex- 
ecuted at that point. This allows you to insert put statements into the code dynamically, without having to 
recompile the program. 

For example, for the factorial program above, we insert a command to print the value of n when fact is en- 
tered: 
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> at (fact, 3) a 
>cs 


fact (3) = 6 
Program terminates normally. 
> quit 


10.8 Conditional Breakpoints | 
ee ee ee ee 
points. The command: 

> at (fun, 27) when(x > 37) stop 
tela the debugger io check the value of very ine ne 27 of subprogram Ban is reached If the value of 
x is greater than 37, a breakpoint occurs. 
The conditional expression for when must be of a boolean type. The debugger supports Ada’s pre-defined 
comparison operators: =, /=,<, <=, >, >=. Noother operators are supported, but the expression can call a user— 
defined boolean function to test for arbitrarily complicated conditions. 
For example, if you defined the following package: 


package counter is i 
- gp: integer := 0; 


function check(i: integer) return boolean; 


+ 
1 


package body counter is 
function check(i: integer) return boolean is 


begin 
n:3n +1; — increment counter 
if i <n then i 
return false; -- not there yet 
else 
n := 0; — reset for next use 
zeturn true; -- this is the one 
end if; 
end 
end; 


and you entered the following debugger command: 

> at (fun, 27) when (counter.check(10)) stop 
then the program will reach a breakpoint on the tenth time that line 27 of subprogram fun is reached. 
The action specified in a when command doesn’t have to be a stop command. Any legal command can be 
specified. 
For example the following line of code prints the value of x every time line 27 of subprogram fun is reached, 
if the value of x is greater than 37, but in either case, the program does not stop. 

> at (fun, 27) when(x > 37) x 
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The when command is nomally only useful inside of an at command. If a when command is entered at 
command level, its effect is that of an 1£ statement. A stop command is normally only useful in a when 
statemenit. ira st op command is entered at command level, its effect isto make the next continue command 
be a single step (ss). 


10.9 The Command Processor 

The Meridian Ada Debugger includes a sophisticated command processor that is designed to minimize the 
amount of typing required to debug a program. 

10.9.1 Identifier Completion 


pletion again. A second completion key displays the possible completing identifiers. 


For example, in the following command, the lower-case characters are typed by the programmer, and the UP- 
per—case characters are-supplied by the command. processor at points. where the ESC key is pressed: 


> datABASE (indEXVAL) . COMPONENT . nexTFIELD 


Because of this facility, you are free to use long, expressive names for identifiers without incurring additional 
typing costs while debugging. This enhances the readability and maintainability of your programs. 


10.9.2 Command History 


The command processor also includes a history mechanism with an editing capability. You can retrieve pre- 
vious commands which can be edited and re-executed. If a complicated data structure is under investigation, 
you can type several complex component references that differ only in small ways. The history and editing 
facilities can greatly speed up the typing of such commands. Also, when an incorrect expression is typed, 
the history and editing facilities can be used to quickly correct the error. 

To retrieve the previous command, the Control- K (4K) or up arrow key is used. Each Control-K (‘K) 


orup arrow key typed moves backwards one command. The Control-J (AJ) or down arrow key is used to 
advance forward in the command history. 


10.9.3 Command Editing 


The editing facility includes commands to move left or right through the command one character or one identi- 
fier at a time and commands to insert or delete characters or identifiers. Editing commands are control charac- 
ters, arrow keys, or other special keys such as DEL or END. The Control-Q (*Q) character (for question) 
can be typed at any time for editor help. The list of keys that are used in command editing are: 
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Control-A (4A) 

Control-F (AF) Delete to end of line i 
Control-H (“H) or leftarrow § Move cursor left one space 
Control-J (4J) or down arow Next history command 

Control-K (4K) oruparrow _— Previous history command 
Coatrol-L (AL) orright arrow Move cursor right one space 
Control-N (AN) Enable/Disable insert mode 

Coatrol-R (4R) Redraw current line i 
Control-S (4S) Delete current character 
Control-T (AT) Move right one word 

Coatrol—U (4U) Delete entire line 

Control-V (“V) or END Move cursor to end of line 
Coatrol-W (AW) Move left one word | 

Control-X (4X) Delete current word 
Control-Y (4Y) or HOME Move cursor to start of line 

DEL Delete previous character 
ENTER/RETURN Execute current line 

ESC Complete current identifier ' 


10.9.4 Function Keys 


t 
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The most frequently—used commands that do not require parameters are associated with the function keys on 


So ee ee ee eee ee 
the input buffer and executed. The function—key commands are: 


Function Command 


2. 
Fl Help 
F2 Cc 

. F3 Ss 
F4 Go 
FS Stack 
F6 Where 
7 More 
F8 Find 
F9 List 
F100) = Quit 

10.10 Special Commands 


10.10.1 Start-up Commands 


If the file debug . ind exists in the current working directory when the debugged program begins, the debug- 
ger reads commands from the file. This can be used to avoid having to set the same breakpoints many times 
while debugging a program. 

It is also a good place to use the silence command, which causes the debugger to suppress the normal 
breakpoints at the start and end of a program. When this is done, the debugger is not heard from unless an 
execution error or breakpoint occurs. 


The debug. ini file also often contains source commands for specifying the location of the program 
source code. 
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10.102 Redirecting Debugger /O 
The commands set _input and set output can be used to redirect the debugger’s input or output to a 


file or a different device. The programs I/O is unaffected. Each of these commands takes a single string pa- 
rameter: 


> set_output (“results -txt”) 
> set_input (“aux:”) 
10.10.3 Executing DOS Commands 


The execute command can be used to execute a DOS command from within the debugger: 
> execute(“dizr *.ada”) 
if no command is specified, a DOS command processor is invoked, allowing you to type many DOS com- 
mands. The DOS exit command retums to the debugger. 
10.11 Exceptions 


The Meridian Ada Debugger includes a facility for causing breakpoints to occur whenever an exception is 
raised, and for examining the state of the program after an exception has propagated out of the main procedure. 


10.11.1 Breakpoints When Exceptions Are Raised 


If an exception is raised by a program during a debugging session, itis propagated and handled normally. The 
command excbreak can be used to cause a debugger breakpoint whenever an exception is raised: 


> excbreak (true) 
A boolean parameter is required; true enables the feature, and false disables it. 
Consider the following test program: 


procedure excdemo is 
a: array(1..10) of integer; 


procedure p(n: integer) is 
begin 
a(n) :2 37; 
end; 
begin 
p(3); 
p (12); 
end; 


If we run this program under the debugger, with excbreak enabled, we reach a breakpoint when the excep- 
tion is first raised: 
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> excbreak (true) 

Exception constraint_error raised 
Breakpoint at line 3 in p (line 6 in excdemo.ada) 
3* a(n) := 37; 


You can continue from such a breakpoint, but if there is no exception handler for the exception in the program, 
the exception propagates out of the main program, and the program terminates abnormally. 


10.11.2 Exception Propagation — 


For programs that contain no exception handlers, it is always a good idea to enable excbreak. This can be 
done in the debug . ind file. If the program handles many exceptions, then excbreak may Cause too many 
breakpoints during normal execution to be useful. If excbzreak is not enabled, and an exception is propa- 
gated through the main program, a breakpoint is still reached. In this case, the debugger may be used to find 
the location where the exception was first raised, and the st ack command shows the call chain, but the values 
of parameters and local variables may have been destroyed by the time the breakpoint i is reached. To set a 
breakpoint when an exception is handled, simply use breakp to set a pe in the exception handler. 


10.12 Tasking 


The Meridian Ada Debugger includes several features to facilitate the debugging of programs containing 
tasking. Breakpoints can be set in task bodies in the same way that they are setin subprograms, by specifying 
a task unit name and a relative line number. For task types, breakpoints that are set in the task body apply to 
any object of that task type. 


i 


10.12.1 Examining Task Objects 


When an object of a task type is given as a command, it is printed in a format similar to an aggregate, contain- 
ing pieces of information about the task. The information printed is: 


e The name of the task object. 
@ The internal name of the task object. 
@ The-execution state of the task. 
e@ The source line where the task is currently executing. 
10.12.2 Printing Task Names 
In many situations, the debugger must print the name of a task, as in the output of the where command, but 


not all tasks may have names meaningful to you. The pre-defined procedure aectaeene can be used 
to assign a more recognizable name to a task. 
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For a simple task object, the name of the task is automatically initialized by the tasking runtime, For tasi Ob 
jects that are components of structures or dynamically allocated, the task name is not set. Inthis case, an Aust 
nal name is used to identify the task. This name is generated by prefixing the character ’T’ to a unique task 
ordinal. Consider these declarations assuming tsk is a task type: 


a: tsk; 
b: array(1..2) of tsk; 


In this example, the name of task a is “a”, but the name of task b(1) is “T2”. The pre-defined procedure 
settaskname may be used to assign a more recognizable name to a task: 


> settaskname(b(2), “b2”); 
It should only be called for tasks that are not simple objects. 
10.12.3 Execution States . 


A task may be in any one of the execution states listed below. The states should be self-explanatory given 
a sufficiently detailed understanding of standard Ada tasking. 


e Inactive 
e Being activated 
e Currently running 
e Ready to run 
e Waiting for activation of dependents 
e Waiting for delay 
e Waiting for entry call to retum 
e Waiting for timed entry call 
e Waiting at accept statement 
© Waiting for rendezvous to complete 
e Selective wait with timeout 
e Selective wait with terminate _ 
e Waiting for completion of dependents 
e Aborted 
e Completed 
e Terminated 
10.12.4 Breakpoints on Context Switches 


You can request that a breakpoint occur whenever an Ada task context switch occurs: This is done by calling 
the taskbreak procedure: 


> taskbreak (true) 
When a Boolean parameter is supplied the following action occurs: 
e true enables the feature and breakpointing can occur. 
e false disables the feature and no break point occurs. 
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At the breakpoint, the names of the task being suspended and the task being resumed are printed. The debug- 
8er context is the context of the task being suspended. A single-step command, ss, advances the context to 
that of the task being resumed. 


In some cases, the tasking runtime can detect a task deadlock. In this case, a debugger breakpoint is always 
reached, regardless of the status of taskbreak. 


10.13 Visibility Issues 
This section discusses visibility issues and qualification of variables or subprograms. 
10.13.1 The Dynamic Call Chain 


; | 
As mentioned in previous chapters, subprogram calls and variable references can be made from the debugger 
only subject to visibility constraints. This means that in any given debugging context, one must be able to 
“see” a variable or a subprogram to make use of it. The rules conceming what is or is not visible are slightly 
more complicated in debugger commands than they are under normal circumstances in Ada source programs. 
For example, suppose that a variable named 4. occurs as a local variable in several subprograms that call each 
other in succession: - 
procedure visdemo is { 


procedure c is — 


procedure b is 


begin 


end visdemo; 


Procedure a calls b, which in tum calls ¢. If a breakpoint is reached in procedure c, then a reference to the 

variable 4 refers to the most recently seen instance of 4 (the one in c). To refer to a'specific instance of a local 

variable i, the variable reference must be qualified with the name of the active procedure in which it occurs: 

a.i Refers to the instance of 4 in procedure a. Procedure a must be active, or a reference to a. isnot 
allowed. 

b.i Refers to the instance of 4 in procedure b. Procedure b must be active, or a reference to b. 4 is not 
allowed. 1 

c.di Refers to the instance of 4 in procedure c (this is the same as 4 in this examaple). Procedure .c must be 
active, or a reference to c. 4 is not allowed. 

i Alone refers to the most recently seen name 4. For example, if ab int is triggered in a, then 4 
refers to a. 4. If a breakpoint is triggered in b, then 4 refers tob . 4. Simi: y, if a breakpoint is trig- 
gered in c, then i refers to c. i. 
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procedure i active it tis pst ofthe dynamic call chan tat ay procedure displayed by #£ 9% 


The debugger treats parameters as local variables. Consider this example: 
procedure myproc(a, b: integer) is 
ce: character; 
begin 
null; 
end; 


rie parameters a and b may be referenced as myproc .2 and mypeoc .b just sie local aah mid 
be referenced as myproc..c— provided, of course, that procedure mypz00 1s active. 


10.13.2 Visibility and Scope 


Objects local to subprograms (1.c. local variables and nested subprograms) may not be referenced in debugger 
commands unless they are visible. Subprograms and variables declared inthe outermost partof alibrary pack- 
age (i.e. global objects) are always visible. Local variables and nested subprograms are visible only if they 
are active. This definition of visibility provides somewhat more flexibility than the normal Ada static scoping 
rules. Consider this example: 
procedure scopedemo-is- = 0 
i: integer; 


In this example, procedure scopedemo calls nested procedure p2, which in tum calls procedure p1. Proce- 
dure p1 is at the same static scoping level as p2. If a breakpoint occurs in p1, references to 4 will refer to 
dure Bi i a np2. The Ada compiler resolves references to 4 within procedure pi tothe 1p scopedemo. 
The Ada language uses “static scoping” and the Ada debugger uses “dynamic scoping”. Dynamic scoping 
is more useful during debugging (because debugging focuses on the dynamic properties of a program), but 
Sanu be aware ofthis sue difference nthe visibility rues. Problems with dynamic vs. static scoping 
sibility issues should never arise in well-written Ada code. 

10.13.3 Package Qualifiers 


Variables and subprograms may be qualified with the names of the packages in which they occur as in Ada 
by using “dot notation”. Consider this package: 


package test is 
x, y: integez; 
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package body test is 
P, @: boolean; 


Note that packages are considered to be active in a top~down order (in reverse order of the elaboration of ini- 
tialization code). This means that when there are collisions among the names of glpbal objects, the last elabo- 
rated units win: un—qualified references to global objects refer to the “most recently seen” objects, just as with 
subprogram activations. Global objects in the main program are always most recent in the order of activation. 


If a debugger command is hidden by a user-defined symbol, it may have to be qualified with the prefix de- 
bug. and some intrinsic subprograms may have to be qualified with the prefix standard. 


For example: 


debug .breakp (test .b) set breakpoint at test .b. 
debug.c continue from breakpoint. 
q :™ standard.true patch the Boolean value of q. 


These qualifications of debug and st andard objects can be necessary because the pre-defined packages 
debug and st andard are farther down in the dynamic call chain than user-defined units, thus user—defined 
subprogram or variable names may collide with debugger commands (for example, ifc is a user-defined vari- 
able). 


For purposes of debugging, you should refrain from defining an object, subprogram, package, or enumeration 
value with the name debug or standard and should also refrain from redefining the other debugger com- 
mand identifiers. 1 ' 


10.14 Overloading 


An Ada program may have many subprograms or enumeration literals with the same names. In this case, the 
name is said to be overloaded. The best way to distinguish between two distinct entities with the same name 
is through the use of “dot notation”. For example, if a function £ appears both in package a and package b, 
the function in package a could be displayed with this command: 
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> print (a. £) 

In many cases, however, several overloaded occurrences of the same identifiermay appear in the same pack- 
age, e.g. text_io. put. 

10.14.1 Identifying by Position 

sta single package has more than one occurrence ofa given identifier, dot notation isnot suiiciens OOS 


eck ee ror is case, a special indexing constructs used to identify particular entities. For exam. 2 
sume there are two different procedures p in package g: 


package g is 
procedure p(x: integer) ; 
procedure p (y, =z: integer) ; 
end; 
They can be accessed from the debugger by specifying a position value enclosed in Bracke: 
> print (g.p[1]) 
procedure p(x: integer) is 
> breakp (g-p[2]) 
Since the position number is the position within a particular package, that package must be specified as part 
of the name using dot notation. Note that the bracket characters are not normally legal Ada characters. 
The numeric position value is determined by the orderin which the overloaded entities are defined. Fora pack- 


has a breakpoint set on it. If there is any doubt about which position value a particular subprogram has, the 
print erPesdure should be used 1 print the header of that subprogram. If no position is specified, postion 
1 is assumed. 
10.14.2 Calling an Overloaded Subprogram 
When calling an overloaded subprogram interactively from the debugger, a position number must be speci- 
fied: 
> g-p{1] (37) 
> g-pl2] (73, 99) 
10.14.3 User-Defined Operators 
User-defined operators are accessed from within the Meridian Ada Debugger as they are from Ada, by en- 
closing the name in double—quotes. For example, consider a single “*” function declared in a package p: 
function “*"(a,b: complex) return complex; 
This function may be accessed as expected from the debugger: 
> breakp (p.”*”) 
If asecond ”*” function is declared in the same package: 
function “*” (a: complex; k: float) return complex; 
then a position number must be specified: 


> breakp(p.”*”[1]) 
> pzint (p.7*” (21) 
function “*” (a: complex; k: float) return complex is 
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These operators may be called from the debugger using prefix notation only: 
> p.”*”" [1] (x,y) 
10.144 Recursive Occurrences of the Same Identifier 
The poston munber can lobe wed 1 distinguish dale occurences ofthe sme variable (see section 
10.13). Consider the following function: 


> print (fact) 
1 function fact(n: integer) is 


else 


ssc’ tose gl wits ol bua ie ean 1°) Aa con te Hmacion oA cao aL then when 
me react the brcalpole here ee oe ‘as shown by this call back- 
trace: 

> stack t 

fact (n => 0) 

fact (n => 1) 

fact (n => 2) 

fact (na => 3) 


We can examine the value of the innermost parameter n simply by typing its name. But to examine other dy- 

namic occurrences of n, a position number must be used. In this case, the numbers correspond to their posi- 

tions within the stack, the “outermost” (least recent) m having the largest ees number. For example, at 
this breakpoint we can look at all invocations of n: 


= 
n[1} : 
n[2] 
n[3] 


n[{4] 


WVNHVEVOVOV 


Note that n and n[1] refer to the same object. 
10.15 Examining Memory 


The raw dump command (xaw) enters a mode in which memory-_locations may.be dumped in “raw format”, 
as bytes, integers, and other primitive data formats. This mode should only be used as alast resort; itis usually 
much easier to look at memory using normal Ada variable references. 


10.15.1 Command Forms 
| 


When the debugger goes into raw dinnp mode; ix prompt changes to, “s:” . There are two command forms 
accepted in raw dump mode: a memory address to dump, or a quit command to return to the main debugger 
command level. 


t 
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A memory dump command in raw dump mode has the form: 

hex-addressiformat 

This command form prints the value at the specified address using the specified format. 

Am address includes a segment and an offset separated by a colon. If there is no colon, the input is assumed 
to be an offset, and the previously specified segment is used. 

To leave raw mode, type Control-Z (AZ) and press ENTER. The prompt changes back to aright angie brack- 
et (“>”), and all normal debugger commands may then be given. 

10.15.2 Formatting Information 


Memory locations may be examined by specifying a hex address, optionally followed by formatting informa- 
tion. The formatting information specifies how a data value is to be dumped (as a byte, an integer, or some 
other primitive data type). If the formatting information is missing, the last format specified is used. If the 
olidiva ig missing, then the previous address is incremented by an amount appropriate to the size of the data 
format, and that next location is dumped. This allows you to step through memory without having to re—speci- 


fy an address or a format; just a carriage retum may be given to request a dump of the next location. 


Formatting information consists of aslash“/” followed by a size spec, a type Spec, orboth. The size spec speci- 
oo he siz of the object to be printed in bytes. Valid size values are 1,2.0r4. The type speciisa letter specifying 
as what data type the data is to be printed. The type formats are: 


S| Pawar tary imager saetbyieiong 
ts [ rimesacancen steigord 
a | Pancasa decimal inege sine byealong 
—o [Paras am ooaimeger sizebyientong 
a 


Print as a real, size ignored 


5 [ranrasa poimer ex aes) eigpord 
aed 


Print as a hex integer, size bytes long 


10.16 Debugger Command Reference 


The debugger calls are listed below with their parameters. Items in typewxiter font are literals to be typed 
as part of the command; italicized items indicate information that you must supply. A parameter listed in 
square brackets [] is optional; the square brackets are not to be typed as part of the command. An example 
command follows. 


breakp( subp [, line] ) 
Here, breakp is acommand to be typed literally; subp can be a subprogram name and line is a specific line 
number. 
Note: Ifa debugger command collides with a user-defined subprogram name, the debugger command must 
be qualified with the prefix debug., as in: , 

debug. breakp (myproc) 


tf you have named a local variable, using the same name asa debugger command, then typing te comm 
displays the value of the variable. This means that the debugger command does not execute. To execute the 
debugger command instead of displaying the variable value, type: 
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debug. [command_name] 
See Section 10.13 for more information. 


Some commands that do not require parameters have been assigned to function keys. For acomplete list, see 
section 10.9.4. 


—_—_—_—————————————eeeeeeeeeeeeeeeeaoaoaooea_aem™=> 
at — execute a command at a specified location 


Format at( subp (, line] ) command 


Description Setting an at breakpoint causes the specified command to be executed whenever the speci- 
fied line in subprogram subp is encountered. This command has a slightly unusual form: the 
command to be executed appears after the parameter list. Any legal debugger command line 
is accepted for command. The subprogram subp must be visible when the at. command is 


the beginning of subp; if line is—1 then the command is inserted at the end of the subprogram. 
A command inserted with at. is removed with the unbreakp command. 


Note: All compilation unit initializations are completed before the first debugger prompt, so 
it is not possible to insert commands with at in the initialization sections of these units. 


For more information, see section 10.7.2. 


oo oooonmnmac—aaoaao 


breakp - seta breakpoint 


Format breakp( subp [, line] ) 

Description The breakp command sets a breakpoint at the subprogram subp. The subprogram must be 
visible when the breakpoint is set (see Section 10.13). | 
If line is specified, then the breakpoint is set at the specified source statement line number, if 
line is not specified, then a breakpoint is set at the beginning of the subprogram; if line is—1 
then a breakpoint is set at the end of the subprogram. 
A breakpoint is cleared with the unbreakp command. 
Note: All compilation unit initializations are completed before the first debugger prompt, so 
it is not possible to set breakpoints in the initialization sections of these units. 


OOOO“ "= 


C-—continue from breakpoint 


Format c 
Description The c command continues execution from a breakpoint. Formore information, see section 
10.6.2. 
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dump (subprogram) - pein vaives of variables 


Format dump( subp ) 


Description The dump command prints (“dumps”) the values of all local variables and subprograms in 
the subprogram subp. 
The dump command may also be used to dump packages (see next section). 
For more information, see section 10.5.3. 


dump (package) - tist subprograms and print values of variables 


lists all subprograms in the specified package. 
Variables and subprograms occurring in both the specification and body sections of a pack- 
age are listed. 


For more information, see section 10.5.3. 


dumpall — dump current program status 


Format dumpall 


Description The dumpal1 command dumps the values of all local variables and subprograms in active 
subprograms, starting from the most recently activated subprogram (see Section 10.13) and 
ending with the main subprogram. 

Following the local information about the main subprogram, the values of all global variables 
in all units are dumped, starting from the main program, and proceeding through the “high- 
est” units (those at the top of the unit hierarchy), and going through the “lowest” units (those 
units that would be initialized first). 

For more information, see section 10.5.3. 


excbreak - select exception breakpoint handling 


Format excbreak( Boolean ) 


Description The excbreak command specifies what action should be taken by the debugger when an 
exception is raised. 
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If the Boolean parameter is given as true, a debugger breakpoint occurs whenever an excep- 
tion is raised by the program. : 

If the Boolean parameter is given as false, the effect is undone; normal program—defined ex- 
ception handling is performed. 


a —anvrovomv= 
execute ~ execute a system command 


Format execute(command) 


Description The specified Ada string is executed by the operating system. The string need not be constant, 
a variable, even a slice or a function call may be used. For more information, see section 
10.10.3. 


4 4 


—_—_——_—_—————————onaoavvvorv' 
find —1ocate a source code fragment: 


Format £ind[(pattern)] 


Description The £ind command is useful when printing a large subprogram. After a source code frag- 
ments listed by the print command, a subsequent £4nd command will search the current 
subprogram for the specified string patiern parameter and resume printing there. 

The pattern parameter may be any expression of type stxing. 


If the pattern parameter is omitted, the string pattern given in the last £ind command is 
used. 


—_—_—<—<———————————————rrrraeae—orovv—omm 
O — run to temporary breakpoints 


Format go[( line [, alternate-line] )] 


Description The go command continues execution from a breakpoint until)the specified line is reached. 
An alternate-line may be specified. Two lines may be specified so that, for example, lines in 
the then and else parts of an if statement may be specified. 

If no lines are specified, the next line in the current subprogram is executed. Note that this 
behavior is slightly different from the single-step command ss; ago command skips over a 
subprogram call, while an ss command steps into the call. 

A go command never executes past the end of the current subprogram, unless the current 
breakpoint is at the end of a subprogram already. 


For more information, see section 10.6.2. 


ee SSESEEOOOOmOmO oo''"=_ 
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help — print debugger help information 

Format help 

Description The help command prints a help message. The message lists the available debugger com- 
mands. 


a ce ae a ee 
eee 
list —tist execution controls and monitors 


Format list 


Description The List command lists breakpoints, tracepoints, and watches. All previously set break- 
points, tracepoints, and watches are listed. 


a a 
oe Oe 
MOFe - continue source code listing 


Format more 


Description The more command prints ten more lines of the source code for the subprogram specified 
with the last print, where, or find command. 


cnr 
aa LL LL 


print — list source code fragment 


Format print( subp [, line} ) 

Description The print command reads the source file containing the subprogram subp and prints ten 
lines of the source code for subp. 
If no line number is specified, then printing starts at line 1 of subp. 
See also more command. 


2 
————————————— esses 
quit — exit debugger 


Format quit 


Description The quit command terminates the current debugging session and retums to the DOS com- 
mand interpreter. 


2 
————— Sess 
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FAW -— enter raw memory dump mode 


Format raw 
Description The xaw command enters raw address dump mode. | 
Refer to Section 10.15 for more information about this debugger, command. 


j 


2 


set_input - redirect debugger command input 


Format set_input( file ) 
Description The set Anput command redirects input from the specified file. The file name parameter 


may be any expression of type string. 

Commands are read and executed from file until the end of the file is reached, whereupon the 
debugger accepts commands from the terminal again. 

If a program being debugged does lots of terminal input, the debugger's 1/O may interfere 
with the program's use of the screen. This command may be used to redirect debugger input 
to be from a file, or from another device: 


set_input (“AUX: ”) 


1 


a 


set_output - redirect debugger output 


Format set_output( ile ) 


Description The set_output command redirects debugger output to the specified file. The file param- 
eter may be any expression of type string. 


Output can be redirected back to the terminal by passing the empty string to set_output. 
ne 
ee eee 


settaskname - rename task 


Format settaskname( task [, new—name] ) 
Description The sett askname command sets the “print name” of the spetified task to be the specified 


If no new—name parameter is specified, the current name is printed. 


fs 


a a 
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silence - inhibit starting and ending breakpoints 

Format silence 

Description The silence command deletes the implicit breakpoints at the start and end of the program. 
This is used most effectively in the debugger startup file (see Section 10.10.1). 


ec SS SS SS 


ge A 


SOUPCE -— reset default program source path 


Format source( path ) 

Description The source command finds source files in the directory specified as the path parameter. 
The path parameter may be any expression of type string. The specified directory path is 
used whenever aprint command is given. The debugger always searches the current direc- 
tory first. 

Path is a string value conforming to file system conventions for directory specifications. 


Example source ("c: \src”) 


a, 
eee 
SS -— single-step 


Format ss 


Description The ss command executes single program step. The code corresponding to a single source 
statement line is executed, following which control is retumed to the debugger. If a call is 
executed, the breakpoint occurs at the start of the called subprogram. 


Note that the go command can be used in place of ss to “skip over” a call. 
For more information, see section 10.6.2. 


2 
EE 
stack -— print stack trace 


Format stack[(levels)] 


Description The stack command prints a “stack trace”. Information is displayed about the state of the 
call stack, which includes which subprograms have been called and with what parameter val- 
ues. 


Subprograms are listed in reverse order of activation, with the most recently activated sub- 
program being listed first, in the manner of the execution stack. 
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Levels indicates how many subprogram calls to display. If it is missing then the entire call 
stack is listed. 


taskbreak - select task switch activity 


Format taskbreak( Boolean ) 


Description Thetaskbreak command specifies what action should be taken by the debugger whenev- 
er a task context switch occurs. " 


If the Boolean state parameteris given as true, then a debugger breakpoint occurs ateach task 
context switch. If the Boolean state parameter is given as false, then the effect is undone. 
H 


For more information, see section 10.12.4. 


ee EOOaOoOoOw oom" 


trace - trace subprogram execution 


Format trace( subp ) 
| 


Description The trace command sets a tracepoint in subprogram subp. A tracepoint may be cancelled 
with untzace. For more information, see section 10.7.1. d 


: 
traceall - trace ali subprograms 


Format traceall 


Description The traceal1 traces all subprograms. This effect may be cancelled with untraceall, 
but individual tracepoints may not be cancelled with unt raceall. For more information, 
see section 10.7.1. | 


ee —ooOOOOOOooomm™m™ 


unbreakp - cance! breakpoint 


Format unbreakp( subp (, line} ) 


Description The unbreakp command deletes a previously set breakpoint at the subprogram subp. The 
subprogram must be visible when the breakpoint is deleted (see Section 10.13). 


If no source statement line number line is specified, then the breakpoint at the start of subp is 
deleted; if line is specified, then the breakpoint at that source line number is removed. 


nS 
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untrace - cancel subprogram trace 


Format untrace( subp ) 


Description The untrace command deletes a previously set tracepoint in subprogram subp. The un- 
tzace command does not affect the tzaceall command. 


ee A SSS SST 


nT SL 


untraceall — cancel traceall 


Format untraceall 


Description The untraceal1 command cancels the effect of the traceall command. The untra- 
ceall command does not affect tracepoints set with the trace command. 


ee ee eee ee ee 
Le eee 
unwatch — cancel variable watch 


Format unwatch( var ) 
Description The unwatch command deletes a previously set debugger watch over the variable var. 


ee ee ee ee 
aS 
watch — monitor the state of a variable 


Format watch( var ) 


Description The watch command monitors the value of variable var. When the value of var changes, a 
message is printed showing the original value of the variable and its current value, and a 
breakpoint occurs. 


A watch is cancelled with the unwatch command. For more information, see 10.6.3. 
EE 
where - locate current source statement 


Format where 


Description The where command prints the line where execution is currently suspended. Five lines of 
“context” source code are printed before and after the current line. 


The name of the currently executing task (if applicable) is also printed. 


eee 0—0_0—0000WOo>oo 
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‘This chapter documents the Extended Mode Meridian Ada compiler. This feature is not available in ail ver- 
sions of the compiler. Some of the discussion may be of interest to those with the standard DOS version of 
Meridian Ada. This chapter discusses how the Extended Mode Meridian Ada compiler can be used to create 
programs that run in Extended Mode. 


Meridian Ada programs can run in Real Mode or Extended Mode. The primary difference between the two 
modes is in the amount of memory that a program can occupy and use. Extended Mode programs can be much 
larger than Real Mode programs. 
Important 

Extended Mode Meridian Ada is available separately from the standard DOS version of Me- 

ridian Ada. There are additional run-time licensing issues to consider for programs created 

with Extended Mode Meridian Adathat are intended for further distribution. These licensing 

issues are discussed in the Licensing, Registration and Support section of the Meridian Ada 

documentation package. 


11.1 Extended Mode vs. Real Mode 


The vast majority of programs that run under DOS are smaller than 640K and operate in Real Mode. Real 
Mode programs run on any DOS system, barring any peculiar system dependencies. Meridian Ada produces 
Real Mode programs by default. Computers based on 8086 or 8088 processors, guch as the IBM PC/XT and 
IBM PS/2-30, run only in Real Mode. 


Extended Mode Meridian Ada programs can take advantage of up to 16 megabytes of extended memory. 
Computers based on 80286 or 80386 processors, such as the IBM PC/AT, IBM PS/2--60, and IBM PS/2-80, 
can accommodate extended memory and may run either in Real Mode or in Extended Mode. 


Regardless of the kind of processor used, programs running under DOS generally operate only in Real Mode 
and cannot use more than 640K of memory without special support. The Extended Mode version of Meridian 
Ada provides the necessary special support to use any extended memory installed in a system. 


11.2 Benefits of Extended Mode 


Extended Mode is also known as Protected Mode because the operating system is largely protected from 
applications running in that mode. In Real Mode, the operating system and application programs co-exist in 
the same address space, leaving the operating system vulnerable to any problems in application programs that 
may crash the system. In Extended Mode, there is a separation of the address that protects the operating 
system against most common problems that may arise in application programs, such as attempts to write into 
code space or unassigned memory. Such problems are usually caught before they can crash the system and, 
in Extended Mode programs, raise the program_error exception. 

This additional protection can help during the debugging phase of a program, especially when used with the 
Meridian Ada Debugger. 

In addition to a better degree of protection from erroneous program behavior, Extended Mode operation also 
provides access to extended memory of up to 16 megabytes. The Extended Mode compiler uses extended 
memory to permit much larger programs to be compiled. ; 


i 


| 
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11.3 Expanded vs. Extended Memory 


Itisimportant to make the distinction between expanded and extended memory resources. Expanded memory 
using the Lotus-Intel-Microsoft (LIM, also called EMS) protocol permits areas of memory to be switched 
among each other within the 1MB address space of Real Mode. A Meridian Ada program may be built to 
make use of LIM expanded memory, provided that the program performs the low-level operations to switch 
the memory banks and the necessary bookkeeping to keep track of what objects are in which memory bank. 
There is no special run-time support presently in Meridian Ada that automatically takes advantage of LIM 
expanded memory resources. The compiler itself does not use LIM expanded memory. 

Extended memory uses a conventional segment addressing scheme that permits up to 16 megabytes of 
memory to be addressed at one time. Extended memory is directly supported by the addressing modes of 
80286 and 80386 processors, and can be used by Extended Mode programs. The Extended Mode compiler 
itself takes advantage of any installed extended memory to compile much larger programs than are possible 
with the Real Mode compiler. 


11.4 Using Extended Mode 
The following chart takes you through the basic steps for using Extended Mode. More detailed explanations 
of the steps are located in the sections that follow. 


1. Create an executable program using the ada command. This program can be created in cither 
Real or Extended Mode. 


ada prg_name.ada 
You can use command options just as you nomnally would with any real mode program. 
2. Link the program using bamp with the command option —x. 
bamp -x prg_name 
The -x option creates an executable with a . exp extension. 
3. Reconfigure the compiler to run in Extended Mode using the adaext command. (This step can 
be performed at any point in the process but it must be performed before you use ramp to run 
_ the program. See section 11.4.2 for more information.) 


adaext 
4. Use the ramp command to run the program. 

ramp prg_name 
11.4.1 Creating Extended Mode Programs 
To create an Extended Mode Program use the -x option with bamp as shown in the following example: 

bamp -x program_name 

The Extended Mode configuration of Meridian Ada.can be used to create either Real Mode or Extended Mode 
programs that run under DOS. The determination of whether a program is to run in Real Mode or Extended 


Mode is made at link time, using the bamp —x option to select Extended Mode. If the ~2 option is not given, 
programs are created to run in Real Mode. 


If the program being compiled is to run in Extended Mode, it may be desirable to use the ada -£S option 
to produce 80286 instructions. 
11.4.2 Increasing Compiler Capacity Using Adaext 


If a program is very large, or consists of a large number of compilation units, it is possible for the compiler 
to run out of memory. With the Extended Mode compiler, it is possible to run the compiler itself in extended 
mode, freeing more memory to use during compilation. 
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By default, the compiler runs in real mode, with the normal memory limitations. ‘The command, adaext, 
reconfigures Meridian Ada so that the compiler, optimizer and linker take advantage of extended memory. 
Exaended Mode remains in effect undl it is undone by the adaxeal. command which retums the compiler 
to Real Mode. 

The mode in which the compiler is run has no relationship to the mode in which the resulting program is run. 
For example, a program can be created to run in extended mode using a compiler running in real mode, of 
areal mode program can be created by running the compiler in extended mode. The adaext and adareal 
e cramands control the mode in which the compiler runs, and the ~2 option to bamp specifies the mode in 
which the created program should run. ae 


11.4.3 Running Extended Mode Programs 


There are two kinds of Extended Mode programs: bound and unbound. All Extended Mode programs are 
initially unbound, and to run them, the zamp command is used. 7 
Bound programs may be created with the separately availablebind command. Thebind program combines 
the program with all the special run-time code necessary for your program to operate in Extended Mode into 
asingle DOS .exe file that runs just like any other DOS program without the need for the zamp command. 
Contact Meridian Software Systems to obtain the bind program and an Extended Mode run-time license. 
The bamp —x option produces an unbound Extended Mode program file with the extension . exp. An un- 
bound Extended Mode program is started by using the ramp program, as in this example: 

ramp extp ; 
This example loads and runs an extended mode program file named exxtp . exp. |Itis not necessary to supply 
the . exp extension. Command line arguments or I/O redirections may be given on the same command line, 
as in this example: 

ramp extp -o file.out < data.txt . 
The only difference in invoking an unbound Extended Mode Meridian Ada DOS program vs. anormal DOS 
program is that the Extended Mode invocation is prefixed with the samp command. 
When the zamp program is used to invoke a _@xp program, the samp program first loads the Extended Mode 
support software (OS/x86), then loads and runs the Extended Mode program. 
The samp command requires that the adaext.command has been run. This is only an issue if the compiler 
is being run in real mode to generate programs running in extended mode. For thle more common case of run- 
ning the compiler and the created program in extended mode, the adaext command should be in effect al- 
ready. The reason for running the real mode compiler is that it is a little bit faster than the extended mode 
compiler. This cost should be weighed against the cost of having to run adaext. before ramping the program 
and adareal after ramping. 


11.5 System Requirements for Extended Mode 


Extended Mode Meridian Ada programs can run on the vast majority of 80286 and 80386—based computers 
that run DOS. Systems that do not have the correct type of processor to use Extended Mode include the IBM 
PC/XT (8088 CPU) and the older model IBM PS/2-30 (8086 CPU). The Real Mode Meridian Ada compiler 
does run on the older IBM PS/2-30 (8086 CPU) and the IBM PC/XT (8088 CPU). 


Although Extended Mode Meridian Ada is expected to run on most 80286 and 80386—based computers with 
DOS, the following systems do not accommodate Extended Mode Meridian Ada; however, Real Mode pro- 
gram are accommodated: 


e Televideo 
e ARC 286 Turbo 
e Orchid PC Turbo 


i 
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11.6 Distributing Extended Mode Programs 


Extended Mode Meridian Ada programs operate in conjunction with a DOS—extender facility called OS/x86, 
which is licensed for use with Meridian Ada by ERGO Computing Solutions. The terms of this license are 
given in the Licensing, Registration, and Support section of the Meridian Ada compiler documentation pack- 
age. An Extended Mode Meridian Ada Vantage program intended for further distribution requires a separate 
run-time licensing arrangement. Contact Meridian Software Systems, Inc. for details. 


11.7 DOS Compatibility in Extended Mode 


Extended Mode Meridian Ada programs are DOS compatible; most Meridian Ada programs do not have to 
be modified to run in Extended Mode, even those using facilities in the DOS Environment Library and theMe- 
ridian Ada Utility Library. A few DOS facilities available in the DOS Environment Library are not meaning- 
ful or are not supported in Extended Mode; these are documented separately in the OS/x86 Developers Refer- 
ence Manual. Contact Meridian Software Systems, Inc. to obtain this document. 


11.8 Effects of Extended Mode on Memory Organization 


The memory organization of Meridian Ada programs is documented in Chapter 13. The same organization 
applies both to Real Mode and to Extended Mode programs. Extended Mode Meridian Ada programs have 
access to more code space and heap space, depending on the amount of extended memory installed in the sys- 
tem. Extended Mode programs are also allocated more main program stack space by default, but the upper 
limit on stack space is the same for both Real Mode and Extended Mode programs. 


The meaning of an address is slightly different in Extended Mode. Refer to section 14.9 for a discussion of 
machine addresses. 


Interfaces between Extended Mode and Real Mode programs are possible; these are discussed in the OS/x86 
Developers Reference Manual. Contact Meridian Software Systems, Inc. to obtain this document. 


11.9 Effects of Extended Mode on Run Time Performance 


The Extended Mode Meridian Ada compiler and Meridian Ada programs running in Extended Mode tend 
to run somewhat more slowly than their Real Mode counterparts. This is primarily because of the way DOS 
operations are supported under Extended Mode. To use DOS, which resides in the base 640K memory area 
and runs only in Real Mode, programs are automatically switched between Extended Mode and Real Mode. 
All disk file operations, for example, use DOS. Because there is no direct support (in the 80286 processor) 
for switching from Extended Mode to Real mode, the switch requires the processor to be reset, which also 
restarts the BIOS. This tends to slow things down. 
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Groupware is a collection of library management features that maintains the integrity of libraries in multi- 
user environments such as UNIX and Local Area Networks (LANS). 


in.a large scale programming project itis likely that more than one programmer inight be accessing ® B'V= 
library at the same time. If the library is being updated by one programmer then allother programmers’ access 
should be blocked until the update is complete. The Groupware components accomplish this goal on certain 


Note: This feature is not available in all versions of the compiler. 
12.1 System Requirements 


Groupware features are included for DOS Extended Mode Meridian Ada, which is provided with the Meridi- 
an Ada product. ‘The Meridian Ada product is shipped to you with both an Extended Mode and real mode 
compiler, however multi-user integrity is guaranteed only when all users on the L,AN use the Extended More 
compiler. This minimizes the memory use of the real mode compiler, which cay be constrained in the 640K 
memory space of the real mode DOS. 


Groupware relies on file sharing services provided in DOS 3.1, and should work with any LAN product which 
supports those services. Groupware has been tested on Novell’s Netware v2.15, Sun’s PC-NFS v3.01, and 
on Invisible Software’s NET/30 v1.50. 


Using Groupware with PC-NFS and a Sun server requires PC-NFS 3.0.1 and SunOS 4.0.1 or later. The host 
file system must be mounted in sharing mode. In order for the host file system to be mounted in sharing mode 
you must use the /must share switch with the net use command or the ms option for the nfsconf 
“mount” menu. Thismay only work on Sun file systems, other types of UNIX may not support PC-NFS prop- 
erly. You must have the rpc. ‘Lockd daemon running on each servermachine. Ifa Groupware process seems 
to be hung for no apparent reason, check to see whether rpc. lockd is still active throughout the system. 
If rpc. lockd daemon is not, then restart it on the appropriate machine. 


12.2 Using Groupware 


The local library is accessed in an exclusive mode that prevents other Meridian Ada tools from reading or 
writing to it. Non-local libraries are accessed ina sharing mode that prevents other Meridian Ada tools from 
writing to them but allows them to be read. The 1s1ib and bamp commands also access a local library in 
the sharing mode since they do not update the library. 
When you try to access a library that is already in use, Groupware issues the message: 

... waiting for access to file 
At this point you can either wait or cancel your process using Control—C (4C). Keep in mind that while you 
are waiting, you could be preventing someone else from accessing some of the libraries you are using. Itis 
also possible that while you are waiting for access to a library, the programmer with control of that library 
might be attempting to access a library that you are using. This form of circular deadlock should also be con- 
sidered when linking libraries and planning the library structure for a prograthming project. Above all, do 
not attempt to have two or more users compiling the same module into the same library at the same time. 
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12.3 Library Creation and Maintenance Tracking 


To provide helpful tracking for project management purposes a user name and group name is automatically 
associated with each new library unit compiled into the library, and on each subsequent recompilation. In 
addition, the mod1.ib command can be used to provide user specific information in the library header. 
You can communicate a user name and group name to Groupware by setting the DOS environment variables 
user and group to the desired values on your workstation. These values are limited by the DOS command 
buffer size to less than 118 characters. 


The person that initially creates a Meridian Ada library will have their user name and group name (if available) 
recorded in both the Library created amd the Library updated fields. 


The person that initially adds an entry to the library, by compiling a source file, will have their user name and 
group name (if available) recorded in both the Entered on and Changed on fields. Subsequent updates 
will replace only the Changed on field for the units in that file. , 


If user and group infonnation is available in the library it is displayed in conjunction with the related field. 
Forexample, if user Joe in the Project_X group updated a unit in a library, a line similar to the following would 
be seen in the library header listing: 

Library updated on Mon Aug 28 1989 16:27:55 PDT by <Joe, Project_x. 


If either a user's name or their group name were unavailable at the time that the library was changed then the 
corresponding item in the display would be left out. If both were missing then the entire by clause would 
be omitted from the above listing line. 


12.4 Managing Project Libraries 


Although Meridian Ada tools can coordinate library access between themselves, when using non~Groupware 
programs, care must be taken to avoid situations where data consistency is at risk. For example, be careful 
_ not to edit a file or rename a library while it is being compiled. 


A new command, mod14b, is available to help manage a programming project’s libraries. With it you can 
arbitrarily lock a library against update or insert additional documentation information in the library header. 
See section 19.12 for more information on using modlib. 


The drive letter and path used for mapping to a server must match the corresponding drive and path used dur- 
ing the Meridian Ada installation or library creation process. 


The documentation and internal library name strings will be limited by the DOS command buffer size to less 
than 118 characters. 
12.5 System Considerations 


Executable (. exe) files need to be marked as read-only with the DOS attrib command if they are to be 
shared. 


NOTE: If the compiler is being shared it should .remain.either in real mode or Extended Mode to prevent 
user conflicts. If this is not the case, then any user that wants to switch modes will need network permission 
in the paclib directory to create, delete and rewrite the avext and ada files. 


A message similar to the following may occur (very rarely) when using the Ada compiler: 


Sharing Violation error reading drive F: 
Abort, Retry, Ignore? 


OR 
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Network Error: file in use during CREATE A FILE. File = F:simple.iis 
abort, Retry, Fail? 


The best reply isa for Abort, since this message should not occur during proper operation ofthe complst 
Tihs wecaenge recurs with subsequent uses of the compiler and you are unable to discem its cause, try Wang 
4 for Ignore once before replying Abort. Sometimes the Ignoze reply allows the error to percolate up 
toa proness that can issve amore intelligible message. If you are sure that you know why the message 6 oo 
ring and still want to conti compiling then Retry can be used. In general, itisnot recommended that you 
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Chapter 13 Memory Organization 


i 


This chapter explains how programsuse memory and offers several helpful hints for making the most of avail- 
able memory. 


zation of a Meridian Ada program. Some of the information presented in this section tends to require a more 
advanced understanding of certain aspects of the 80x86 processor architecture. | 

There are several kinds of memory allocations that are presently bounded by the BOx86 segmented architec- 
ture. Meridian Ada currently supports one memory model, amedium-large model, which is used both in Real 
Mode and Extended Mode programs (see Chapter. 11 for a discussion of Real and Extended Modes). This 
memory model permits large amounts of code and data, but places bounds on individual pieces of code and 
data. Simple workarounds are described throughout this chapter for those progréms that bump into architec- 
tural limits. Section 13.2 discusses options for working with and within memory restrictions. 


13.1.1 Code Size 
The size of a single compilation unit presently may not exceed 64K bytes of code. This is not usually a prob- 
lem, because: 
1. The total amount of code in a program is limited only by available memory; the limit is only on 
individual compilation units. 
2. Ada is designed so that use of smaller, separately compiled units is very easy. 
{ 
Each individual compilation unit is assigned its own code segment. The limit to the size of an 80x86 code 
segment is 64K bytes, hence the limit on the size of a compilation unit. 


13.1.2 Global Data Size 


The total amount of global data in an entire program (as opposed to a single compilation unit of a program) 
cannot exceed 64K bytes. This is not a serious problem because the 64K limit on global space does not apply 
to heap space. Programs can use access types and dynamic allocation instead of large global objects. Refer 
to section 13.1.5 for information about how to do this. 

One 80x86 segment is assigned for the global data. Since the data segment register is not changed by the pro- 
gram code, and global data offsets are only 16 bits wide, global data references are very fast, and the code 
is more compact. The limit on the amount of globat-data is the result of this choice of model. 


13.13 Stack Size 


The maximum amount of stack space that may be allocated for a program is 64K bytes. This limitation must 
be considered for: 


e The amount of space allocated for local variables. Note that dynamic allocation may 
be used to work around stack space problems for local variables (see section 13.3). 
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° The number of tasks activated in a program (see Chapter 6). 


© The activation depths of subprograms (the number of subprogram calls active at the 
same time). ; 

A Real Mode application program that does not use tasking has 20K bytes of stack space allocated for it by 
default. If tasking is used, then an additional 20K bytes (40K bytes total) is allocated by default. The amount 
of stack space allocated to a program may be increased or decreased at link time by using the —M and —s op- 
tions to bamp, but the absolute maximum is 64K bytes. 
An Extended Mode application program that does not use tasking has the maximum 64K stack size allocated 
to it. If tasking is used, then 20K bytes within the 64K stack segment are reserved for use by tasks. As with 
Real Mode programs, the amount of stack space allocated to a program may be increased or decreased at link 
time by using the -M and -s options to bamp, but the absolute maximum is 64K bytes. 
For an individual task, the default maximum stack size is 1024 (1K) bytes. This may be changed at compile 
time. Refer to Chapter 6 for an explanation of how to do this. 
The program stack is assigned to one 80x86 segment. Since the stack segment register is not changed by the 
program code, and stack offsets are only 16 bits wide, stack references are very fast, and the code is more 
compact. The limit on the size of the program stack is the result of this choice of stack model. 


13.1.4 Individual Data Object Size 


The size of a single data object may not exceed 64K bytes. This means specifically that very large arrays and 
records cannot be declared. Note that this is also not often a problem because linked lists and other dynamic 
data structures, which are not subject to global data or stack space limitations, are easily created by allocators 
(new) and destroyed with unchecked_deallocation. 


Each data object must fit within 64K because indexes or offsets are sixteen bit quantities. 
13.1.5 Heap Storage 


The heap is an area of memory where certain dynamically instantiated objects are created, such as intemal 
temporaries created by concatenation with “&” (see section 2.4.4) and objects instantiated with new. The 
amount of memory available for the heap is that which is left over after memory has been allocated for operat- 
ing system overhead, the program stack, and program code. The heap grows as memory allocations are re- 
quested by a running program. 

Heap storage for temporaries is reclaimed automatically on source block boundaries. Heap storage for objects 
allocated with new must be reclaimed by calls to instantiations of the generic procedure un- 
checked_deallocation. 

See section 13.3 for an example of how new and unchecked_deallocation can be used. 

As with any other object, a dynamically instantiated object must fit within 64K bytes, because indexes or off- 
sets are sixteen bit quantities. An object of precisely 64K bytes may be instantiated. 

The heap management scheme used by the Meridian Ada run-time depends on the DOS memory allocation 
and deallocation system calls. 

13.1.6 Storage Collections 


A storage collection is allocated from the heap when the scope of the associated access type definition is en- 
tered and deallocated when the scope is left. 


13.2 Running Out of Memory 


A program may run out of memory at the time it is loaded ((.e. it exceeds the capacity of DOS) or at some 
point when it is running. This section discusses what can be done if a very large application program exceeds 
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the capacity of DOS at load time. Some of the discussion may apply also to what can be done with stoxr~ 
age_error exceptions. Amore complete discussion of what to do when a storage_erxor exception 
is raised while the program is running is given in section 13.3. A discussion of what to do when the compiler 
runs out of memory is given in section 3.2. 
If a large application program exceeds the capacity of DOS, some options are: . . 
1. Scavenge memory by reducing or eliminating system facilities that compete with the application 
Section 3.2 offers some suggestions for doing this; many of the same system configura- 
tions that affect the compiler may also affect an application program. 
2. Use the Meridian Ada Optimizer with your program. Chapter 7 discusses program optimization. 


3. Split the program into several smaller cooperating programs. This may require use of the DOS 
exec function. The DOS Environment Library provides this capability. 

4. Use Extended Mode. If more than 1MB of extended memory is installed in the system, using 
Extended Mode permits a program to take advantage of the extended memory resources. Chapter 
11 discusses Extended Mode. 


13.3 Storage_Error Exceptions 


The storage_errox exception may be raised if, forexample, you declare a very large array inside a proce- 
dure. Objects declared inside procedures (local objects) are placed in the program stack, where they occupy 
space only temporarily until the procedure retums. The amount of stack space is limited by the 80x86 archi- 
tecture. Entering a procedure in which a 30,000-element array is declared may “blow up” the stack, resulting 
ina storage_error exception. 
To explain in more detail, the amount of stack space available at a particular moment varies according to the 
amount of stack space consumed by each subprogram activation. Space consumed by an activation includes 
the space for the parameters, return addresses, and local objects. A local array is going to consume space on 
the stack when the subprogram containing the array is called. That space is reclaimed when the subprogram 
returns, but if the subprogram is called recursively, or many levels of subprogram calls are involved, then the 
additional amount of stack space consumed by each call must be considered. 
The maximum stack size is 64K bytes, but only 20K is allocated to the stack by default unless you specify 
a larger stack size with the -M option to bamp. For example: 
bamp -M 32000 alloc demo 
For a task, a length clause should be used, possibly in conjunction with the ~s option to bamp. 
Another way to manage the stack space is to use allocators, as in this example: 
with unchecked_deallocation; 
procedure alloc_demo(n: natural) is 
type presto_dynamo is array (natural range <>) of integer; 
type presto_dynamo p is access presto_dynamo; 
procedure dispose is 
new unchecked_deallocation (presto_dynamo, presto_dynamo_ p) ; 
dynamo: presto_dynamo_p; 
begin 
if n > 0 then 
dynamo := new presto_dynamo (0... n-1); 
for i in dynamo’ range loop 


dynamo (i) := i; 
end loop; 
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dispose (dynamo) : 
end if; 
end alloc demo; 


This example subprogram dynamically allocates a one dimensional array of n elements, indexed from 0 to 
n— 1, with new. Ina for loop, the array is filled with numbers. When that is done, the array is disposed of 
and the space for it is reclaimed. : 

More importantly, the array access object dynamo only takes up eight bytes on the stack. The array itself is 
created dynamically on the heap, leaving lots of room on the stack for more subprogram calls, parameters, 
and local objects. Note that except for the set-up code (the declarations and the one new statement) and the 
take—down code (the di spose call), there is little or no visible difference between using an allocated array 
and an ordinary array. 
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This chapter describes intemal-data representations used by-Meridian Ada. Address clauses, representation 
specifications, and the effects of pragma pack are also discussed. ; 


14.1 Discrete Types 
This table shows the number of bits used by predefined discrete types: 


} 


Typeboolean is represented using aneight-bit byte, unless itis present in apacked composite type, in which 
case it may be compressed to a single bit. aa. 
Type character is represented using an eight-bit byte. The representation of type character may be 
slightly modified in a packed record, but not in a packed array (effectively). | 
Types byte_integer, long_ integer, and integer are 8, 16 and 32+bit twos—complement inte- 
gers. The representations of the pre-defined integer types are unaffected by their presences in packed compos- 
ite types. Programs that must rely on specific precisions of integers for portability should use range defini- 
tions: ' 


type int8 is range -128..127; —- 8-bit integer type 
type uns8 is range 0. .255; -- 8-bit unsigned type 
type int16 is range -32_768..32_767; -- 16-bit integer type 
type unsl6 is range 0. .65_535; —- 16-bit ugsigned type 


type int32 is range -2_147_483_648. .2_147_483_ 647; . 
— 32-bit integer type 


An enumeration type occupies 8, 16, or 32 bits depending on the number of values declared for the enumera- 
tion. 

In general, a discrete type not appearing-in.a packed-composite type is- represented in the smallest number of 
bits, rounded up to the nearest number of bytes, that accommodates the range of values in that type. No sub- 
type is represented in a smailer number of bits than its base type. Consider this declaration: 


subtype small_range is natural range 0. .255; 
The subtype small_xange in this example is actually represented in 16 bits. 


A discrete type appearing in a packed composite type is packed to the smallest number of bits that accommo- 
dates the range of values in that type. Consider these declarations: 
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subtype small_range is natural range 0..255; 


type byte _array is array(1..64) of small_range; 
pragma pack (byte_array) ; 
The type byte_array is represented in 64 bytes. 


A discrete type with a dynamic bound is always represented in the same mumber of bits as the base type. An 
example follows: 


nm: constant integer := 7; 
subtype count is positive range 1..n; 


Type count in this example is represented in 16 bits whether or not it appears in a packed composite type. 
The effects of packing are discussed further in sections 14.4, 14.5.4 and 14.6.2. . 
14.2 Real Types 


This table shows the number of bits used by real types: 


data type description | bits | 


The representations of real types are unaffected by their presences in packed composite types. 
14.2.1 Floating Point Representations 


Meridian Ada uses a 80x87 64-bit floating point format for all floating point objects. This format conforms 
to the IEEE 754 standard for floating point. 


14.2.2 Fixed Point Representations 
Fixed point objects are represented as machine-integer objects with imaginary decimal points. Whether a 
fixed point type is “byte”, “short”, or “long” depends on the delta and range values specified for the type. 
Length clauses to specify fixed-point ’ smal1 values are implemented. Justas an application note, this facil- 
ity is useful where exact representations are needed. An example follows: 

type money is delta 0.01 range -1_000_000.0 .. 1_000_000.0; 

for money’ small use 0.01; 


The length clause formoney’ smal1 allows exact (unrounded) computations in increments of 1/100. Note 
that this is perhaps a naive approach to real-world financial computations; take it as a simple example only. 
In the absence of the length clause, the Ada language requires that the default value of money’ smal1 be 
147, amore efficiently handled value, but a value that can lead to some roundoff errors. 


14.3 Enumeration Representation Clauses 


Enumeration representation clauses, which are described in section 13.3 of the LRM, are supported. An enu- 
meration representation clause is permitted following the type declaration to which it applies, provided that 
the representation clause occurs within the same declarative part as the type declaration. Note that the type 
declaration and the accompanying representation clause cannot be split across a package specification and 
body. 
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Here is an example program that demonstrates the use of enumeration representation clauses: 


with text_io; 
with unchecked_conversion; 


procedure stepper is 


type command is ( 
none, 
forward, 
backward, 


stop, 
motor _on); 


for command use ( 


none => 16900%#, -—- 0 decimal 

forward => 16#10#, -- 16 
backward => 16#11%, -- 17 

motor_on => 16#1f# -- 31 


): 


function value is new unchecked_conversion (source => command, 
target => integer); 


function field(s: in string; width: in positive) 
return string is 
£ : string (1 .. width) := (others =>’ '); 
sii: positive; 
£1 : positive; 
begin 
_si := 8’ first; 
fi := £' first; 


{ 
| 


while si <= s’last and then fi <= f’last loop 
£(f4) := s(si); 
fi := £1 +1; 
si := si + 1; 

end loop; 


return £; 
end field; 


use text_io; 
begin 
for i in command loop 
put_line (field (command’ image (1) , width => 10) & “POS => “6 
integer’ image (command’pos(i)) & “, VALUE => “* 6 
integer’ image (value (4)))-; 
end loop; 
end stepper; | 


The output of this program is: 
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none pos 


=> 0, value => 0 
forward pos => 1, value => 16 “sy 
backwardpos => 2, value => 17 : 
stop pos => 3, value => 30 
motor_onpos => 4, value => 31 


Note that there is no language—defined facility in Ada for obtaining the underlying values of enumeration ele- 
ments for which a representation clause has been specified. In the Meridian Ada implementation, un- 
checked_conversion between the enumeration type and an integer type may be used to obtain the val- 
ues. 


14.4 Pragma Pack 


Pragma pack is implemented for composite types (records and arrays). 


Pragma pack is permitted following the composite type declaration to which it applies, provided that the 
pragma occurs within the same declarative part as the composite type declaration, before any objects of the 
composite type are declared. 


Note that the declarative part restriction means that the type declaration and accompanying pragma pack 
cannot be split across a package specification and body. 


The effects of pragma pack are discussed further in sections 14.5.4 and 14.6.2. 
14.5 Array Types 


14.5.1 Constrained Array Objects “oy 


A constrained array object with static bounds occupies just the space required for its elements. For example: 


a: string (1..10); 
—-a’ first = 1 
--a'last = 10 


In this example, object a takes up just the ten bytes required to hold ten characters (see Figure 14.1). 


«[TTTTTITTi Ly 
Figure 14.1 Constrained Array with Static Bounds 
14.5.2 Dynamic Array Objects 


A dynamic array object (an array with variable bounds) is represented as a pointer to a memory area contain- 
ing the actual array elements. The memory area for the array elements is created on the dynamic allocation 
heap. Separate temporary objects are created to hold the variable bounds of the array; these temporaries have 
the same duration as the dynamic subtype—Global “temporaries” with permanent duration are created for 
global arrays with dynamically computed bounds; local temporaries are created in the stack for local arrays 
with dynamically computed bounds. No storage overhead is incurred for a static bound; the compiler keeps 
track of such bounds. An example follows: 


n: integer := 7; 

b: string(1..n); 
—b’ first = 1 “sy 
--b’/last = n 
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In this example, object b takes up the space required for the pointer as well as the space required for the cle- 
ments (see Figure 14.2). Also, a temporary is created to hold the upper bound of the array since a subsequent 
change to the value of n should not effect this dynamic afray. 


a 


Figure 14.2 Dynamic Array 
14.5.3 Unconstrained Array Objects 


An unconstrained array object (also an array with variable bounds, typically a parameter to a subprogram) 
is represented as an array access object. ‘An example follows: 

procedure p(s: string); : 

p("abede”) ; 


In this example, the parameter s is passed as an unconstrained array access object (see section 14.7). 
14.5.4 Packed Arrays 


The effect of pragma pack on an array type is to cause packing of discrete type'array elements into 16-bit 
words. | 


} 


element bit elements bits left over 
size packed per | in completely 


word packed word 


* One element per byte; see below 


Arrays whose elements are 6, 7, or 8 bits wide are packed one element per eight~bit byte to maximize efficien- 
cy of access. For example, an array of type character arranges the characters on eight-bit byte bound- 
aries, with one unused bit per byte (hence the 1 + 1 notation in the table above). The alternative method, not 


H 
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used, is to pack the characters on adjacent seven-bit boundaries, which would leave two unused bits at the 
end of each 16-bit word, and would involve more code to address each character. “4 


For an example of the array packing method, consider these declarations: 
subtype register_values is natural range 16#0#.. 16#1F#; 


type register_file is array(1..6) of register_values; 
pragma pack (register_file) ; 


The type register_file is represented in two 16-bit words, with three 5—bit elements per word. The 
ordering of packed array elements within a word is discussed in section 14.55. 


Pragma pack has no effect when applied directly to an array of a composite element type. Instead, pragma 
pack should be applied to the type from which the array is built. An example follows: 


subtype small_range is natural range 0..255; 
— An object of this type normally consumes one word. 


type comp is array(0..1) of small range; 
pragma pack (comp) ; 
— This packs type comp into one word instead of two. 


type comp_array is array(1..10) of comp; 
—— An object of comp_array type will consume ten 16-bit words. 


Here, to effect packing, pragma pack is applied to the composite type comp. If pragma pack were instead 
applied to comp_azray, cach element of comp_array would consume two 16-bit words instead of one. 


14.5.5 Array Element Arrangements 


In the absence of packing, elements of an array are arranged in memory so that the last (rightmost) indices >) 
vary faster than the first (leftmost) indices. Ina single dimension, elements are arranged so that the low-order 
elements of the array occupy lower addresses and high-order elements of the array occupy higher addresses. 


Consider these declarations: 


type byte_array is array(1. .4) of character; -- constrained array type 
ba: byte_array := (ra’, ‘b’, ’e', 'a’)? -— constrained array object 


Following initialization of the array object ba, its contents are shown in Figure 14.3. 


pa(1) | ‘a’| ba’ address + 0 
ba (2) | pe | ba’ address + 1 
ba(3) | ‘c’| ba’ address + 2 
ba (4) zs ba’ address + 3 


Figure 14.3 Array Element Arrangement for ba 


Packed array elements are arranged with the first element occurring in the least-significant bits of the byte 
at the low-order address. This means, for example, that packed arrays of character are arranged exactly 
" like unpacked arrays of character. For another example, consider this packed array type declaration: 


type primary is (red, yellow, blue) ; “sy 
--Each element of type primary can be represented in two bits. 
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type color wheel is array(1..7) of primary; 
pragma pack (color_wheel) ; 
wheel: color wheel := (blue, yellow, red, others =>| blue); 
The object wheel is represented in a 16-bit word shown in Figure 14.4. 


MSB/HOB LSB/LOB 
0 


15 
Fandet [tie | blue [ blue [ blue [ red [yellow | blue _ 


Figure 14.4 Packed Array Wheel 


14.6 Record Types 


The components of a record type are arranged in the order in which the components are declared. 


In a discriminant record, the discriminants are treated as components of the reco: and the discriminants oc- 
cur as the first components of the record. For discriminant records whose discrimi may vary at run-time, 
an additional Boolean component appears at the start of the record. This component, the is_constrained flag, 
is used to implement the attribute ‘constrained. The is_constrained field occupies a byte for an un- 
record and a single bit for a packed record: The compiler omits the is_constrained component alto- 
gether if default values are not specified for the discriminants. 
An unconstrained variant record object occupies as much space as is required to hold all the invariant compo- 
nents as well as the components of the largest possible variant of the record. When a specific discriminant 
value is given fora case selector, i.e. the record object is constrained, the size of the record reflects the selected 


variant. 
14.6.1 Discriminant Array Components 
Aconstrained array component in a record occupies as much space as a constrained array object of the same 


type. A discriminant array (an array whose bounds depend on discriminants) is represented as a pointer. An 
example follows: 


type text (n: natural) is 
record 
val: string(1..n); 
end record; 


x: text(5); -- note: no default value for x.n 
— x.val’ first = 1 
—— x.val/last = x.n = 5 ; 


In this example, x. val is effectively a dynamic array, represented as a pointer to the elements of the array 
(see Figure 14.5). : 
x: 


ACA gE eM se, [i A 


t 
' 


Figure 14.5 Record with Discriminant Array 
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14.6.2 Packed Records 


The effect of pragma pack on a record type is to cause enumeration and discrete range components to be 
cates soe ty ores ene er ar Anexample 


type command word type is 


record 
xt_address : integer range 0..31; 
transmit : boolean; 


sub_address: integer range 0. 31; 
word_count : integer range 0. .31; 
end record; 


pragma pack (command_word type) ; 


Specifying pragma pack for type command_word_type is equivalent to specifying this record represen- 
tation specification: 


for command _word type use 


record 
xt_address at 0 * word range 00 .. 04; 
transmit at 0 * word range 05 .. 05; 


sub_address at 0 * word range 06 .. 10; 
word_count at 0 * word range 11 .. 15; 
end record; 


The intemal layout of an object of the packed type command_word_type is shown in Figure 14.6. 


MSB/HOB . LSB/LOB 
15 11 10 6 5 4 0 


Figure 14.6 Packed Record 
14.6.3 Record Representation Specifications 


Record representation specifications, also called “rep specs”, are implemented. A record rep spec is permitted 
following the record type declaration to which it applies, provided that the rep spec occurs within the same 
declarative part as the record type declaration, before any objects of the record typeare declared. The stylisti- 
cally preferred place of a record rep spec is immediately after the type declaration. 


Note that the declarative part restriction means that the type declaration and accompanying rep spec cannot 
be split across a package specification and body. 


Consider this record type declaration: 
word: constant := 2; -- Storage unit is byte, 2 bytes per word. 


Meridian Ada Compiler User’s Guide 100 


+) 


Internal Data Representation 


record 
xt_address : integer range 0. .31; 
transmit : boolean; 
sub_address: integer range 0. .31; 
word_count : integer range 0. .31; 


end record; 

for command_word type use 

record 
xt_address at 0 * word range 00 .. 04; 
transmit at 0 * word range 05 .. 05; 


sub_ address at 0 * word range 06 .. 10; 
word_count at 0 * word range 11 .. 15; 
end record; "4 


Given this rep spec, the internal layout of an object of type command_word_type is shown in Figure 14.6. 


The current implementation-dependent restrictions on record rep specs are: 
1. The storage unit offset (the at static_simple_expression patt) is a ward offset and must be even. 
2. Bit positions (the range part) may be in the range 0..15, with 0 being the least significant bit of 
_ acomponent. 
3, Components cannot straddle word boundaries. 
If a compact representation for a record type is desired, but it is not necessary for the record to correspond 
to a particular externally determined layout, pragma pack should be used instead of a record representation 
specification. 
14.6.4 Alignment Holes 


To maintain alignments (see section 14.8), additional space can be allocated between components ina record. 
Consider these declarations: 


type example is 
record 
a,b,c: character; 
i: integer; 
end record; 
ex rec: example; 


In this example, the record occupies four bytes, not three. The internal layout of the record is shown in 
Figure 14.7. 


ex_rec’address+0 


ex_rec’address+1 


ex_rec’address+2 


Figure 14.7 Record with Hole 
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If the declaration order of the components c and 4 is reversed in record type examp1e, a hole is still allocated, 
as shown in Figure 14.8. 


ex_rec’address+0 


ex_rec’address+2 


ex_rec’address+3 


Figure 14.8 Rearranged Record with Hole 

The hole at the end of the record is allocated because records can be elements of arrays or members of other 
records, and the alignment is then maintained for ex_zec.4 in any data structure. 

In general, the alignment of a record object reflects the alignment of the component with the strictest align- 
ment requirement. 


14.7 Access Types 


An access object is potentially more than just a pointer. A pointer is a low—level object that references a 
memory location. Access objects for most types are represented simply as pointers to those objects. Access 
objects for arrays are usually just pointers as well, but access objects for unconstrained arrays are somewhat 
more complicated. 


A’ address+8 
A’ address+10 


lower bound of 2nd index 
upper bound of 2nd index 


A’ address+0 
A’ address+4 lower bound of 1st index 
A’ address+6 upper bound of 1st index 


Figure 14.9 Array Access Type 

An unconstrained array access object is represented intemally as a structure containing: 
e A pointer to the actual array data. 
e The lower bound and upper bound of each index. 

Figure 14.9 illustrates this structure. 


An access object for a task type references a structure containing information about the task that is used by 
the tasking run-time support code. The intemal layout of a task type is not documented by Meridian. 


14.8 Alignments 


For any address a, and a number n given in the table for the specified machine storage object, a mod n must 
be equal to zero to satisfy alignment requirements. The higher the value of n, the “more strictly aligned” a 
particular storage object is said to be. 
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14.9 Address Clauses 


An Address clause can be supplied for an object (whether constant or variable) or a task entry, but not fora 
subprogram, package, or task unit. An address clause is permitted following the declaration to which it ap- 
plies, provided that the address clause occurs within the same declarative part as the item's declaration. The 
stylistically preferred place of an address clause is immediately after the declaration. 


Note that the declarative part restriction means that the item's declaration and accompanying address clause 
cannot be split across a package specification and body. 


14.9.1 Real Mode Object Address Clauses 


In Real Mode, the address of an object is a 32-bit simple_expression of type SYSTEM. ADDRESS whose 
high-order 16 bits are the paragraph address and whose low-order 16 bits are the offset. A paragraph is 16 
bytes, thus the 16-bit paragraph address 16#007F# represents physical address 16#07F0#; the paragraph 
address is shifted left four bits (simply catenate a hexadecimal zero on the right) to yield the physical address. 
The physical paragraph address resulting from shifting the high-order 16 bits of the address expression is then 
added to the offset in the low-order 16 bits of the address expression. For example, the address 
16#007F_0008# represents the absolute physical address 16#07FO# + 16#0008# yielding 
16#0000_07FS#. 


Note that address expressions are signed 32-bit quantities, thus an address value larger than 


1687F¥F_F¥F¥# must be represented as a negative number. The negative number may be a universal inte- 
ger expression that subtracts 16#1_0000_00 00# from the desired (unsigned) value. An example follows: 


COLOR_GRAPHICS_ SCREEN : SCREEN_ARRAY; 

-- where type SCREEN_ARRAY is some useful 

— representation of the screen... 

for COLOR_GRAPHICS SCREEN use at 
16#B000_8000# - 16#1_0000_0000#; 
-- Handy trick using universal integer 
-- computations to get 16#B000_8000#. 
-- This, by the way, represents physical 
—- address 16#000B_8000#, since the 
— computation is 16#B_0000# + 16#8000#. 


The Real Mode addressing scheme is discussed in the Intel iAPX 86/88, 186/1 88 User's Manual/Program- 
mer's Reference (Reward Books, ISBN 0-8359-3035-1). 


14.9.2 Extended Mode Object Address Clauses 


In Extended Mode, the address of an object is a 32-bit simple_expression of type SYSTEM. ADDRESS whose 
high-order 16 bits are a segment selector and whose low-order 16-bits are an offset within a segment. An 
Extended Mode address expression does not directly represent a physical address. The segment selector is 
an index into an address table maintained by the Extended Mode support facilities. 


The Extended Mode (Protected Mode) addressing scheme is discussed in the /ntel 80286 and 80287 Pro- 
grammer’s Reference Manual (Intel, ISBN 1~55512-055-5). 
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On DOS systems that are running Extended Mode on the main processor (not on a co—processor card or an 
“accelerator” card), a segment selector of 16#00B0# in Extended Mode maps to the monochrome screen 
memory area; a segment selector of 1 6#0088# maps to the color screen memory area. There are more gener- 
al techniques for obtaining access to physical resources such as screen memory. Contact Meridian Software 
Systems for the OS/x86 Developers Reference Manual, which contains additional documentation on DOS 
system programming in Extended Mode; information on Extended Mode system programming is generally 
beyond the scope of this User's Guide. 


14.9.3 Task Entry Address Clauses 
For information on task entry address clauses, see sections F.5.4 and F.5.5. 
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By using pragma interface, it is possible to make calls to subprograms written in 80x86 assembly lan- 
guage, Microsoft-C, or Meridian—Pascal from Meridian Ada programs. This section discusses pragma in- 
terface, machine code insertions, and calling conventions. 


15.1 Formal Description 


Pragma interface specifies that a subprogram is written in some other language and that the definition 
of that subprogram resides in a separate object module. 
The form of pragma interface in Meridian Ada is: 
pragma interface ( language, subprogram [, “link-name”] ); 
where: 
language Thisis the interface language, one of the names assembly, builtin, microsoft_c orinternal. 
The names builtin and internal are reserved for use by Meridian compiler maintainers in 
run-time support packages. 
subprogram This is the name of a subprogram to which the pragma interface applies. 
link—name Thisis an optional string literal specifying the name of the non—Ada subprogram correspond- 
ing to the Ada subprogram named in the second parameter. If link-name is omitted, then 
link—name defaults to the value of subprogram. Depending on the language specified, some 
automatic modifications may be made to the link-name to produce the actual object code 
symbol name that is generated whenever references are made to the corresponding Ada sub- 
. The object code symbol generated for link—name is alw ys translated to upper case. 
Although the Meridian object linker is case-sensitive, it is a rare ject module that contains 
mixed—case symbols; at present, all Meridian 80x86 object modules use upper case only. 


The limit to the number of characters in the link-name depends on the interface language: 


assembly 40 characters 
builtin 38 characters 
internal 38 characters 


microsoft _c 39 characters 


Itis appropriate to use the optional link-name parameter to pragma intexrfaceonly when the interface sub- 
program has aname that does not correspond at all to its Ada identifier or when the interface subprogram name 
cannot be given using rules for constructing Ada identifiers (e.g. the name contains a ‘$’ character). 


15.2 Calling Conventions ; 
| 


The discussion in this section about calling conventions applies to all pragma interface languages except 
for microsoft__c (see section 15.6). 
Itis important to note that at present, no automatic data conversions are applied for any pragma interface 
subprogram parameters; if the data types of parameters are not directly compatible, then explicit conversions 
must be applied by you. 
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15.2.1 Stack Frames 


Parameters are passed by pushing them onto the stack in reverse order of formal parameter declaration (right 
to left), The subprogram must know the number and types of the parameters in order to access the correct stack 
locations. All parameters are passed in the stack. Meridian Ada passes all non-scalar objects by reference, 
regardless of mode. Internal data representations are given in Chapter 14. 

Caution must be exercised in passing parameters to pragma interface subprograms to maintain stack 
frames properly. 

A representation of a stack frame is: 


higher addresses 


caller’s locals 
return address (base) 
return address (offset) 


0 .. n local variables 


SP before call 


SP after 
before ap 


SP after setup 


direction of growth 
lower addresses ( one pony 


The stack frame for a subprogram consists of the actual parameters, the retum address, adisplay, and the local 
variables. The display, which consists of copies of frame pointers from previous subprogram activations, is 
used to make references to local and non-local objects. An explanation of local objects is given in section 
13.3. 


Anon-local object is a special case of alocal object that is used for nested subprograms. When a subprogram 
makes a reference to a local object that is both non-global and not declared in the immediate subprogram 
scope, then the object is said to be non-local. The appropriate frame pointer from the in-stack display must 
be selected to make the necessary non-local reference. 


Saving the previous frame pointers and allocating space for local variables is the responsibility of the called 
subprogram. It is also the respo ibility of the pragma interface subprogram to deallocate the stack 
frame, including parameters, before returning. This can be done by specifying the appropriate number of by- 
tes to deallocate with the terminating RET instruction. 


Helpful Hint 


The compilers the definitive authority onhow subprograms are called. If there are any ques- 
tions about the calling conventions or intemal data representations that are not answered in 
this documentation, then the answers may be determined by examining the assembly lan- 
guage source output from the compiler (see section 19.1). For example, a temporary stub 
subprogram can be written in Ada in place of the non—Ada subprogram. Both the calling sub- 
program and the stub can be com i ed and the assembly language output examined to deter- 
mine exactly how the calling conventions work in a particular case. 
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15.2.2 Register Usage | 
Only the registers SS, SP, DS, and BP must be preserved during the call. All other registers can be destroyed. 
Register DS always points to the base of the global data segment, $$DATA. 
Function retum values are arranged as follows: 

e 8bdit values are retumed in register CL. 

e 16-bit values are retumed in register CX. 

© 32-bit values are returned in registers BX:CX. The most significant word is in BX. 

the least significant word is in CX. 
e 64-bit floating point values are returned in the 80x87 stack top register. 


15.3 Code Model Compatibility . 


Meridian Ada presently uses a single code model that is described in Chapter 13. Non-Meridian language 
systems that do not use this model may require some additional interface code. Some specific aspects 
of the code model that affect compatibility are: 
e Subprogramsare called using 32-bit addresses. Using assembly language parlance, 
this means that pragma interface subprograms must be FAR PROCS. 
e The compiler places all global data in a single segment named $$DATA of class 
‘DATA’. Ifan Ada program is pre-linked with the bamp —z option, the data seg- 
mentis renamed_DATA. Ifit is pre-linked with the bamp -z ~41 options, the data 
segment is renamed DATA. In any case, the data segment must not exceed 64K bytes. 
Ifa different data segment is used, then it is the responsibility of the pragma inter- 
face subprogram to save the DS register and restore it upon return. 
© Meridian Ada code segments are of class ‘ CODE’ . The compiler places each com- 
pilation unit in its own logical segment, and switches the CS register for inter—seg- 
ment calls. : 


e All segments must be aligned on paragraph boundaries. 
15.4 Object Code Compatibility 


The Meridian linker accepts a subset of the Microsoft object module format. This means in general that the 
Meridian linker can accept only Meridian object modules and Meridian libraries with a few rare exceptions, 
e.g. some version 4 Microsoft object modules. Where the Meridian linker cannot be used, the Microsoft link- 
er, the DOS linker, and the Intel linker can accept Meridian object modules that have been pre-linked using 
thebamp -r orbamp -r ~4 options. : 

When pragma interface subprogram object modules are directly compatible with Meridian object mod- 
ules, library augmentation with the aug1ib command can be used. An appropriate auglib command asso- 
ciates information with a Meridian Ada library unit so that the bamp command can obtain the names of exter- 
nal object modules that are to be linked with the rest of the program. 

It is important to note that the Meridian linker is sensitive to case in symbol names (i.e. upper and lower case 
alphabetic characters are distinguished). ; 


15.5 Interface to Assembly Language 


Anassembly language subprogram can be called by specifying the pragma interface language assembly. 
The link—name is used as the object code symbol as specified, with no modification. 
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Machine code insertions may be easier to deal with than assembly language pragma interface subpro- 
grams. Refer to section 15.9 for information about machine code insertions. 
An example of an assembly language subprogram and the Meridian Ada interface code is: 
: 8086 Assembly Language 
Name outport 
. 8087 
DGROUP GROUP $$DATA 
S$SDATA Segment Public ‘DATA’ 
$$DATA Ends 
_outport Segment Public ‘CODE’ 
Assume CS: outport, DS: $$DATA, ES:NOTHING, 8S: NOTHING 


push bp z;save old stack frame 
mov bp, sp set up stack frame 
mov dx, 6[bp] ;port 
mov ax, 8[bp] ;info . 
out dx, ax ;move the bits 
pop bp szestore the frame pointer 
ret 4 szeturn and pop 4 bytes 
;0f arguments 

Outport EndP 

_outport Ends 
END 3; of the program 


-- Meridian Ada code: 
package port is 
procedure put (port, item: integer) ; 
pragma interface(assembly, put, “outport”) ; 
end port; 


begin 
port .put (port => 16#60#, item => 16#418) ; 

end port_demo; 
This example shows how to perform I/O port output using an assembly language routine. 
For an assembler whose object code is directly compatible with the Meridian linker, the object module can 
be associated with the library unit poxt by using the auglib command: 

auglib port outport.obj 

bamp port_demo 
This assumes that the outport object code is contained in a filenamed outport . obj. Note that auglib 
only adds the necessary information to the library entry for package port; auglib does not perform the 
actual linkage. The object file outport . obj is actually linked with the main program when bamp is in- 
voked. 
For other assemblers, the assembly code must be modified slightly and the object module must be linked sepa- 
rately with a pre-linked object module containing the Meridian Ada code. 
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For Microsoft assemblers, the data segment, $SDATA, must be renamed to_ DATA and the program linked 
as follows: . 

bamp -r port_demo 

link /nod /batch port_dem outport ;;; 
For Intel assemblers, rename $$DATA to DATA and link as follows; 

bamp -r -i port_demo | 

link /nod /batch port_dem outport ;;; . 
‘These are examples of how anon-Meridian linker might be used to link the object code for the poxt_demo 
program and the assembly language module outpost . obj. Specific details yary with the linker used. 
For further information on how to interface Meridian Ada programs with Intel assembly programs, see the 
read .me file in the ada/inasm directory. 


15.6 Interface to Microsoft C 


A subprogram written in Microsoft C can be called by specifying the language microsoft_c in pragma in~ 
terface. This interface language changes not only the object symbol name, but also the calling conven- 
tions. 

Object Code and Code Model Compatibilities | 

There is no standard Microsoft memory model that corresponds exactly to the memory model used by Meridi- 
an Ada. Microsoft C subprograms compiled using /AL (lange model) can be used. This is an important 
consideration for linking with precompiled Microsoft C object code modules and object libraries; only li- 
braries compiled with the correct code model can be used. 

Meridian Ada programs with interfaces to Microsoft C must be partially linked:using the bamp =z option 
and finally linked with the Microsoft linker. 

The information in this section about code models, calling conventions, and linkage is valid for Microsoft C 
version 5.0. , 7 


Microsoft C Calling Conventions 
be ee symbol generated for a microsoft_c interface subprogram a oa an underscore (“_”) to 
: The calling conventions are changed in the following ways for a microsoft_c subprogram. 
¢ Function return values are given as follows: | 
| © 8 bit values are retumed in register AL. 
e 16-bit values are returned in register AX. 
© 32-bit values are returned in registers AX and DX, with the most significant word in DX, 
the least significant word in AX. 
| e Floating point values are discussed below. 
| 


© Thecaller(notthe subprogram) is responsible for popping the actual parameters that 
the caller pushed onto the stack before the call. 
These calling conventions are used automatically when pragma interface microsoft_c is used. 


@ Data types are directly compatible for 8, 16 and 32-bit integer types as well as for access values (pointers). 
Enumeration types are directly compatible, except when passed as reference parameters (i.e. are passed by 
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address, as pointers). Microsoft C allocates an integer-size object for an enumeration type, while Meridian 
Ada allocates an object of a size appropriate to accommodate the range of values in the enumeration (8, 16, or 
32 bits). Note that Ada out parameters are passed by reference. 


For floating point values, Meridian Ada supports only type double, the 64-bit floating point type. Floating 
point actual parameters are directly compatible with formal C parameters of type double. Floating point 
function return values are presently not directly compatible. In Microsoft C functions, a float or double 
result is retumed as a pointer to a floating point object. To call such a subprogram directly requires that the 
interface subprogram be specified as retuming an access to a floating point object, and appropriate indirec- 
tions made from there. Here is an example of how such an interface subprogram can be declared: 


package fp interface is 
type fp is access float; 
function f(x: float) return fp; 
private 
pragma interface (microsoft_c, £); 
-—— Microsoft c function declaration: 
— double f(double x); 
end fp interface; 
Note that because of the way Microsoft C retums floating point values as pointers to temporary storage, the 
caller should assign the result to a floating point object as soon as possible, as in this example: 
x: float := fp _interface.f (3.7) .all; 


Data Transformations 


the necessary conversions. 
The source code of a package that provides a conversion facility between Meridian Ada strings and C strings 
and a demonstration program that uses the package follows. It is intended only to provide a guide to how 
such packages can be created. 
File cs .ads: 

with system; 


package c_string_ conversion is 
subtype c_string is system. address; 


procedure ada_to_c (astr: in string; cstr: out string) ; 
procedure c_to_ada( 


estr : in c_string; 
stz_len : out natural; 
astr : out string); 
end c_string_ conversion; 
File cs. adb: 


with unchecked_conversion; 
package body c_string_ conversion is 
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- procedure ada_to_c(astr: in string; cstr: out string) is 


begin 
cstr(1..astr’length) := astzr; 
cstz(astr’ length + 1) := ascii. nul; 
end ada to _c; 


str_len : out natural; 
: out string) is 
: integer; 
Pp : C_string; 
: character; 
type char _p is access character; 


function character_at is new 
unchecked _ conversion (source => system. ‘acmaas 
target => char _p); 


ch := character_at (p) .all; 
exit when ch = ascii.nul; 
astxr(astr’ first + len) := ch; 
Pp :=p +i; 

len := len + 1; 


end c_string_conversion; 
Here is an example of how the conversion routines can be used: 


t 


File z.c: 
/* © function to change each ‘e’ in a string into an ‘x’. */ 


woid z(char *p) 
{ 
char *q; 
if (p) 
{ 
for (q = p; *q; gtt) 
if (*q mm '@’) %q m fxs 


} 


int _acrtused; 
/* This is defined just to resolve an MS C compiler-generated */ 
/* external reference that is not used here but would otherwise */ 


/* vequire linking in the Microsoft-C run-time libraries. */ 
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File z_i.ada: 
with system; 


package s_i is 
procedure z(p: system. address) ; 
private 
pragma interface (microsoft_c, 2) ; 
end z_i; 
File demo _c_i.ada: 


with c_ string conversion; 
with s_i; 
with text_io; 
procedure demo_c i is 
use c string conversion; 


: stxing(1..127); 
a =: string(1..127); 
: natural; 
begin 
ada_to_c(astr => “eschew Escher-esque entries”, cstr => c); 
z_i.z(c(1)’ address) ; 
c_to_ada(cstr => c(1) ‘address, 
str_len => len, 
. astr => a); 
text_io.put_line(a(1l..1len)); 
end demo_c i; 
The example program can be compiled, linked, and run using the following commands, assuming that the 
specification and body of package c_string_conversion are split between two files named cs . ads 


and es .adb, package =_1 is in s_4 .ada procedure demo_c_1 isin demo_c_1. ada, and C function 
zisinz.c: 

rem —— Compile the Ada units. 

ada cs.ads cs.adb z_i.ada demo c i.ada 

rem — Partially link demo_c i. 

bamp -r demo_c_i 


rem — Compile the C unit with MS C using large model code (/AL) . 
vem — Inhibit stack checking, which would drag in MS C run-time 
rem — libraries (/Gs). Hold off linking (/e). 


cl /aAL /Gs /c z.c 


rem -—— Link everything with the MS linker. 
rem —- Use no default libraries (/nod) . 
zem —- Ignore missing files (/batch) . 

rem — Use all file name defaults (;;;). 


link /nod /batch demo_c i 2 77; 
rem -—— Run the linked program. 
demo_c_i 
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The example, when compiled, linked and run, converts the Ada string “eschew Escher-esque en~ 
tries” into aC string, calls a C function that changes all occurrences of the letter e to the letter x, changes 
the C string back into an Ada string, and produces this output: 


xschxw Eschxr-xsqux xntrixs 

Linking Meridian Ada Programs with Microsoft C | 

Thebamp -r option produces a partially-linked file suitable for use with the Microsoft linker. From the 
example in the previous section, the demo_¢_4.. obj file that results from linking with the =z option con- 
tains all the necessary Ada run-time modules and all the program units, but not the object code for the C unit. 
The C unit is compiled separately and the entire program bound together using the Microsoft linker. Meridian 
Ada programs that interface to Microsoft C subprograms or libraries should always be linked in this mannér 
The normal aug1b mechanism for associating non—Ada code modules with interface packages cannot be 
used for Microsoft C interfaces. 


and C program source files, batch files, and object modules. Although the interface techniques discussed 
above are adequate for interfaces to Microsoft C subprograms that do not use much of the Microsoft C run 
time, subprograms that make use-of Microsoft C’s standard I/O, floating point types, and other facilities need 
to perform some additional set-up and take-down. Furthermore, the Microsoft C run-time libraries must be 
properly configured. The necessary techniques are discussed in the xead me file and explored in the sample 
program sources. 


15.7 Interface to Meridian—Pascal 


It is possible to make calls to Meridian-Pascal subprograms, but a matching Merjdian-Pascal export interface 
pragma form must be used in the pertinent Meridian-Pascal unit: 
(* Mexidian-Pascal: *) 
unit demo; interface 
pragma interface (c) ; 
procedure p; 
pragma interface (pascal) ; 
implementation 
procedure p; 
begin 
end; 
end. 


-- Meridian Ada c $ 
package callit is \ i 
procedure p; 
pragma interface(c, p); 
end callit; 
with callit; 
procedure pascal_call demo is 
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In this example, the Meridian-Pascal procedure demo. p is made available to Meridian—Ada programs by 
matching the interface language (c in this case). 

The reason that no interface pascal is available for Meridian- Ada is that in Meridian—Pascal, as in Meridian- 
Ada, compiler-assigned symbols do not look precisely like the programmer-assigned symbols, so Meridian— 
Ada programs making use of Meridian-Pascal symbols would most likely be that much more difficult to 
maintain. It is therefore easier to use c or assembly interface symbol correspondences. 


Calling conventions between Meridian-Pascal and Meridian Ada are directly compatible only for scalar 
quantities and pointers. Meridian Ada passes all nonscalar objects by reference, regardless of mode. Parame- 
ter ordering is the same. 
The aug14b program must be used to associate the Meridian—Pascal subprogram with the calling program, 
as in this example: 

auglib callit demo.obj 


This assumes that the object code file containing the Meridian-Pascal function demo is named demo . ob}. 
Note that aug1ib only adds the necessary information to the library entry for package callit, auglib 
does not perform the actual linkage. The object file demo. obj is actually linked with the main program 
when bamp is invoked. 


15.8 Interfaces to Other Languages. 


Interfaces to other languages are possible provided that the symbol naming conventions and parameter pass- 
ing conventions are the same or that interface subprograms are written to do any necessary conversions. Al- 
though only the interface languages mentioned in section 15.1 are supported, assembly interfaces can be used 
to perform any necessary conversions between calling conventions. 


15.9 Machine Code Insertions 


Machine code insertions, described in the LRM section 13.8, are supported in Meridian Ada. Several forms 
of machine code insertion can be used. Values must be static expressions. There are additional restrictions 
on machine code insertions, as described in the LRM: 
e A compilation unit that contains machine code insertions must name package ma- 
chine_code in a context (with) clause. 
e@ Thebodyof a procedure containing machine code insertions cannot contain declara- 
tions other than use, cannot contain statements other than code statements, and can- 
not contain exception handlers. 


Refer to the LRM for more specific details. 
The definition of package machine _code is: 
package machine_code is 
type unsigned byte is range 0..255; 


type instl is 
record 
bil: unsigned_byte; 
end record; 
type inst2 is 
record 
bi, b2: unsigned _byte; 
end record; 
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bi, b2, b3: unsigned_byte; ‘ 
end record; i 


type instw is 
record 


bi: unsigned _ byte; 
w: integer; 
end record; 
type im is 
zecord — 
w: integer; 
end record; 
type imml is 
record 
1: long_integer; 
end record; 
end machine code; 
The INST1, INST2 and INST3 records are used for creating one, two or three byte 80x86 instructions. The 
INSTW record is used to create a one-byte instruction with a two-byte immediate operand. The IMMW and 
IMML records are used for creating two-byte or four-byte operands. 


with system; 
with machine_code; 
procedure urdbuf (file: integer; 
buf: system.address; 
nbytes: natural) is 
use machine_code; 
begin 
——- This machine code function issues a DOS read data 


-~ from file request (INT 21, function code 16#3F%#) . 


dinstl’ (bl => 16#1E#); -—~- PUSH DS : save DS 
inst3’ (16#C5#, 16#56#, buf’ locof£fset) ; 

-— LDS DX, [BP+08] ; DS:DX := buf 
dnst3’ (1698B#, 16#5E#, file’ locoffset) ; 

— MOV —~&BX, [BP+06] ; BX := file 
inst3’ (16#8B#, 16#42#, nbytes’ locoffset) ; 


— MOV CX, [BP+0C] CX := nbytes 


instw’ (16#B8#, 16#3F00#); -- MOV ax, 3F00 : AH := 3¥ 
inst2’ (168CD#, 164218); -—— Int ai ; dssue DOS call 
instl’ (bl => 16#1F#) -—— POP DS : restore DS 


end; 
The Meridian Ada attribute ' Llocof £set is applied to a parameter and retums the stack offset of that param- 
eter (the offset from the BP register). It allows machine code insertions to access parameters using less error— 
prone symbolic names. 
Check your machine code insertions for correctness. This can be done by disassembling the final object code 
obtained from compilation of a subprogram containing machine code insertions. The DOS debug command 
can be used to do this. 
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15.10 Pragma Runtime_Names 


Pragma runtime_names is intended primarily for use in conjunction with the Meridian Ada Run-Time 
Customization Library. It has the form: 

pragma runtime_names (symbol-form) ; 
where symbol-form is either builtin or ada. . 
The scope of this pragma is limited to the compilation unit in which it occurs (note that a package specification 
and its associated body are separate compilation units) or to the next occurrence of the pragma that uses a 
different symbol-form. 
The effect of pragma runtime_names with symbol-form builtin is to modify the compiler-generated ob- 
ject code symbols generated for all identifiers falling within the scope of the pragma. The generated object 
code symbol name is the user defined identifier name prefixed with two underscores (_ _) (e.g. “example” 
becomes “_ _example”). 
Refer to the Meridian Ada Run-Time Customization Library User's Guide for examples of how to use this 
pragma. 
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16.1 Information About Standard Packages 
The specification of package sy st emis given in Appendix F in this document. Machine code insertions and 
package machine_code (LRM 13.8) are discussed in section 15.9. 
The specifications of the remaining standard distribution packages are described in the LRM: 
e packagecalendar (LRM9.6) 
@ generic package direct_io (LRM 14.2.4) 
e package io exceptions (LRM 14.5) 
e generic package sequential_io (LRM 14.2.1) 
e package standard (LRM Appendix C) 
e package text_4o (LRM 14.3.10) 
e generic function unchecked_conversion (LRM 13.10) 


e generic procedure unchecked_deallocation (LRM 13.10) 
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Chapter 17 Additional Pre—defined I/O Packages 


a 


The full text_4o package is designed to be very useful and flexible, but it can be difficult for novice Ada 
programmers to understand. For example, consider integer input and output. The standard text _4io pack- 
age does not directly define input-output for any particular integer type. Instead, a generic package, inte- 
gex_io, must be instantiated for particular integer types. The standard Meridian Ada package includes sev- 
eral pre-defined packages designed to help overcome this potential problem: 

ada_io A simplified input-output package. 

fio An instantiation of text_40.float_io for type float. 

iio An instantiation of text_io.integer_io for type integer. 
These packages are described in the following sections. 


17.1 Package IO 


The Meridian pre-defined library package 110 consists simply of an instantiation of text_io. inte- 
ger_io for the standard type integer. This allows you to read and write integers without making your 
own instantiations of integer_io. 


The source code for i.40 is simple: 


with text_io; use text_io; 
package iio is new integer_io (integer) ; 
-—- generic instantiated as library unit 


Package Lio can be used directly: 


with iio; 
procedure iexample is 
n: integer; 
begin 
iio.get (n); 
iio.put (n); 
end iexanple; 
Use of package 410 not only makes integer I/O more convenient, butit also terids to be more space efficient, 
since multiple instantiations of the integex_4o generic create distinct copies of the code. 


17.2 Package FIO , 


The package £10 instantiates text_io. float_io on the predefined type float: 
with text_io; use text_io; : 


package fio is new float_io (float) ; 
— generic instantiated as library unit. 


: } 
This makes floating point I/O more convenient and space-efficient, just as iL does forinteger 1/O. Anex- 
ample follows: 


H 
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with fio; 
procedure fexample is 
z: float; 
begin 
fio. get (Zz) ; 
fio. put (rz) ; 
end fexample; 


17.3 Package Ada_IO 


The package ada_4o provides asimple interface to texxt_ 4.0 fordoing terminal input and output. Ada_io 
allows you to learn more quickly by hiding the more subtle aspects of the standard text _io package. 
The package uses text_io, iio, and £10 and consists simply of subprogram renaming declarations. For 
simple terminal input-output, a program only needs to specify ada_io in a with clause. The Ada compiler 
automatically uses the necessary declarations from text_1io and the other packages. 
The specification for ada_io follows: 
with text_io; 
with iio; 
with fio; 
package ada_io is 
procedure put (item: character) renames text_io.put; 
procedure put ( 
item: integer; 
width: text_io.field := 0; 
base: text_io.number_base := 10 
) renames iio.put; ; 
procedure put ( 
item: float; 
fore: text_io.field := 0; 
aft: text_io.field := 0; 
exp: text_io.field := 0 
) renames fio.put; 


procedure put (item: string) renames text_io.put; 

procedure put_line(item: string) renames text_io.put_line; 

procedure new_line (spacing: text_io.positive_count := 1) 
renames text_io.new_line; 

procedure get (item: out character) renames text_io.get; 


procedure get ( 
item: out integer; 
width: text_io.field := 0 
) zenames iio.get; 


procedure get ( 
item: out float; 
width: text_io.field := 0 
) renames fio.get; 
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procedure get_line ( 
item: out string; 
last: out natural 
) zenames text_io.get_line; 


procedure skip_line ( 
spacing: text_io.positive_count sa 1 
) renames text_io.skip_line; 


function end_of_line return boolean renames text_io.end_of line; 


end ada_io; 
By using Ada’s renaming facility, ada_io simply changes the defaults for the text_io formatting parame- 


ters for integers and floats to values that have more intuitive effects (note that when a parameter to a subpro- 
gram has a default value, the parameter may be omitted in the call). Refer to the Ada reference manual for 


information about optional formatting parameters for text _io subprograms. 
If the more advanced facilities of text_1o are needed, then ada_io should most likely be excluded, al- 


though the packages 14.0 and #40 themselves can still be useful. Note that if both ada_io and text_io 
are made directly visible with use clauses, certain subprogram calls are ambiguous. For example, a call to 
put with a character parameter is ambiguous because the put in ada_io and the put intext_ioare both 


visible. To get around this problem, the package can be specified explicitly, as in: 
ada_io. put (ch) 
An example of using ada_io follows: 


with ada_io; use ada_io; 
procedure for_demo is 
begin 
for iin 1..9 loop 
for 4 in reverse 1..i loop 
put (j); — This is ada_io.put. 
end loop; 
new_line; -- This is ada_io.new_line. 
: end loop; 
end for demo; 


When compiled, linked, and run, this program produces the output: 


1 

21 

321 

4321 
$4321 
654321 
7654321 
87654321 
987654321 
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Chapter 18 Using the Utility Library Packages 


{ 


The Meridian Ada Utility Library isa set of Ada packages for use with the Meridian Ada compiler. The utili- 
ties provided with this package are: 


Package arg Provides access to command line arguments. 
Generic Package array_ocbject 
Provides ability to declare array objects larger'than 64K. 


Generic Package array_type 
Provides ability to declare array types larger than 64K. 


Packagebit_ops Provides in-line bit-level operations. 
Packagemath_1ib Provides floating point transcendental functions. 
Package spio Provides flushing for output text files. 

Package spy Provides byte peek and poke operations. 


Package text_handler 
Provides a text handling facility as described in section 7.6 of the LRM. 


The descriptions of the packages are organized alphabetically by package name. Each package is presented 
with its specification, a brief summary of its usage, and a discussion of the details of the package. 
18.1 Package Arg | 


SPECIFICATION ; i 
package arg is 


function count return natural; 
function data(n: positive) return string; 
' end; j 


USAGE 


Package arg provides data from the command line on which the program was ittvoked. This facility is similar 
to the argc and argv parameters provided to C programs. The command line is partitioned where one or 
more space characters (’ ”) occur. Each part, called a command line argument, is placed in a separate Ada 
string. The command line argument strings are ordered according to the position at which they occur on the 
command line, from left to right. | 


I/O redirections (“‘>”, “|”) are discarded prior to program activation by the command line interpreter, thus 
such constructs do not appear in the command line data. 


18.1.1 Function Count | 


Function count retums the number of command line arguments. 
function count return natural; 
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The value retumed by count is nommally 1 or greater. The count includes the reserved index position 1. Valid 
command line arguments in PC-DOS therefore occur at positions 2 through count. If the count is 1, then 
there are no command line arguments. 


For an example see function data. 
18.12 Function Data 


Function data retums the command line argument indexed by n. 
function data(n: positive) return string; 


Valid arguments occur at positions 2 through count. If count retums 1, then there are no command line 
arguments. A constraint error is raised if n is less than 1 or greater than count. 


An example of using package arg with function data follows: 
-- This example accepts command lines of the form: 


prog [-a] [-b] [arg] -.- 


where “prog” is the name of the program, “—a” and 
“<b” are-legal options, and “arg” 4s some optional argument. 


with text_handler; use text_handler; 
with text_io; use text_io; 
with arg; 


unrecognized_option: exception; 
illegal_argument: exception; 
begin 
for i in 2..arg.count loop 
set (this, arg.data(i)); 
— convert string argument to text object. 


4f not empty (this) then 
if value (this) (1) = ‘-’ then 
4f length(this) < 2 then 
raise illegal_argument; -~ argument was just ‘-’ alone. 
end if; 
case value (this) (2) is 
when ‘a!’ => put_line(”-a recognized”) ; 
when 'b’ =>  put_line("-b recognized”); 
when others => raise unrecognized_option; 
— argument wasn’t “-a” or v—b* . 
end case; 
else 
put_line (“argument www 6 walue(this) & “”” recognized”); 
-——- argument didn’t start wi. foe, 
end if; 
else 
raise illegal_argument; -——- argument was empty somehow. 
end if; 
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end scan_command line arguments; 
18.1.3 Non-—ASCII Characters 
Note that it is possible (although difficult) to enter non-ASCTI characters ona command line. Programs that 
donot require non-ASCII characters from the command line should “sanitize” command line data by clearing 
the eighth bits of characters in command line arguments (package bit_ ops provides this capability). Other- 
wise, a program may generate const raint_error exceptions in places where non-ASCII characters in 
command line arguments are used and range checks are performed. 


18.2 Generic Package Array_Object 


SPECIFICATION 
generic 
type index is (<>); 
type elem is private; 
package array_object is 
procedure set (i: index; e: elem) ; 
function get (i: index) return elem; 
end; 
USAGE 
Genericpackage array_object defines an individual array with subprograms set and get to manipulate 
elements of the array. : 
An example of an instantiation of this package is: 
with array_object; : 
package a is new array_object (index => 1..10, 
elem => integer); | 
This instantiation is analogous to this array object definition: 
a: array(1..10) of integer; 
An example of instantiating and using this package is: 
with array object; 
with ada_io; 
procedure btest is 
type block is array(1..1000) of character; _ 
package a is new array_object(character, black); . 
b: block; 
use ada_io; 


H 


for c in character loop 
b := (others => c); 
a.set(c, b); 

end loop; 
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put_line (“init done”) ; 


for c in reverse character loop 
if a.get(c) (37) /= c then 
put line (“fail”); 
end if; 
end loop; 
put_line (“pass”) ; 
end; 
This program instantiates a package defining an array object, indexed by type character, of 1000-charac- 
ter blocks. The first for loop sets each 1000- character element to NUL, SOH, and on upto ‘a’, ’b’,’c’, 
and so on. The second for loop checks the 37th character of each block to see whether it was properly initial- 
ized. 


There are some special considerations for using package array_object: 


e Since array elements must be copied when they are set or fetched, operations on large 
records may have significant overhead. It is best instead to define arrays of access 
types for efficiency. 


© Thesize of an individual element must not exceed.16K bytes. The storage_ez— 
ror exception is raised if this limit is exceeded. Note that this is not a limit on the 
size of the entire array, although there must be enough memory in the system to ac- 
commodate the array. 


© Constraint_error is properly raised for out of range indices. 


e There is currently no way to de-allocate the object created by an instantiation of 
array_object. 


e The size of an element of an array object created with axray_obJect is rounded 
up 1o the next power of two so that array accesses are done more efficiently. Al- 
though this is not a factor for elements of discrete types or access types, it can apply 
to elements that are structures. For example, each array element whose type is a 
structure of size 17 bytes becomes 32 bytes in size. Forthis reason, itis more efficient 
in terms of storage to use an array of access types instead. 


Note: Space for array objects created with generic package array_ob/4ect is allocated from the heap, not 
from the stack or from global memory. This makes the best use of available memory. 


18.3 Generic Package Array_Type 


SPECIFICATION 


generic 
type index is (<>); 
type elem is private; 
package array_type is 
type desc (first, last: index) is limited private; 
procedure set (d: desc; i: index; e: elem); 
function get(d: desc; i: index) return elem; 
private 


end; 
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USAGE 

Generic package array_type defines an array type with subprograms set aad get to manipulate cle- 
ments of objects of the array type. Whereas package array_object defines asingle array object, package 
array_type permits several large arrays to be defined with similar characteristics. 


The same considerations that apply to package array object, discussed in the previous section, with re- 
spect to efficiency of element copying, deallocation, and storage efficiency, also apply t0 package 
array_type. As with array_object, space for array objects defined using generic package 
array types allocated from the heap, not from the stack or from global memory. This makes the best use 
of available memory. a 
An example of an instantiation of package array_type is: 

with array_type; 

package arr is new array_type (index => integer, 

elem => integer); 


This instantiation is analogous to this unconstrained array type definition: 
type arr is array (integer range <>) of integer; 
An example of instantiating and using this package is: 
with array_type; 
with ada_io; 
procedure mtest is 
type rec is 
zecord 
a, b, c: integer; 
end record; 
package arrtyp is new array type (integer, zec); | 
use arrtyp; ; 


zr: rec := (0, 0, 0); 
a: desc(1, 20000); 
x: desc(0, 1000); 


use ada_io; 
begin 
for i in a.first..a.last loop 
z.b := i; 
set(a, i, x); 
end loop; 
put_line(“init done”); 
for i in reverse a.first .. a.last loop 
af get(a, 4).b /= i then 
put_line (“fail”); 
end if; 
end loop; 
put_line (“pass”); 
end; 
This example creates 2 package, arrtyp, that defines an unconstrained afray type, indexed by integer, 
of records of type rec. An array of this type, a, constrained in the range 1 . .20000, is then defined. A 
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second array, x, constrained in the range 0.. 
initialized by a for loop to contain successive 
by a second for loop to ensure that it contains the expected value. 


array a is 
is then tested 


18.4 Package Bit_Ops 
SPECIFICATION 
package bit_ops is 


— Operations on type byte integer (eight bits) : 


function 
function 
function 
function 
function 


function 


*and” (left, 
"or” (left, 
"zor" (left, 
“not” (left: 
shi (left: 


shr (left: 


"and" (left, 
“or” (left, 
*xor” (left, 
“not” (left: 
shl (left: 
shr (left: 


right: byte_integer) 
right: byte_integer) 
right: byte integer) 
byte_integer) 
byte_integer; 


byte_integer; 


right: 


right: 


right: integer) 
right: integer) 
right: integer) 
integer) 
integer; 
integer; 


right: integer) 
right: integer) return integer; 


1.000, is also defined. Each component b of the elements of 
integer values beginning at 1. The same component 


return byte integer; 
return byte_integer; 
return byte integer; 
return byte integer; 
integer) 

return byte_integer; 
integer) 

return byte_integer; 


— Operations on type integer (sixteen bits) : 


return integer; 
return integer; 
return integer; 
return integer; 
return integer; 


— Operations on type long_integer (thirty-two bits) :- 


function 
function 
function 
function 
function 


function 


end; 
USAGE 


Package bit_ops provides highly effic 
optimized by theMeridian Ada compiler, 


“and” (left, 
“or” (left, 
*xor” (left, 
"*not” (left: 
shl (left: 


shr (left: 


right: long integer) 
right: long integer) 
right: long_integer) 
long_integer) 

long_integer; right: 


long_integer; right: 


tions rather than less efficient subprogram calls. 


Note 
types 
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return long integer; 
return long integer; 
return long integer; 
return long integer; 
integer) 

return long integer; 
integer) 

geturn long_integer; 


ient bit—Jevel operations. The functions in this package are specially 
they are translated directly into the equivalent machine-level opera- 
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18.4.1 Function “And” 


The function and retums the bitwise “and” of its operands. 
function “and” (left, right: byte integer) return byte_integer; 
function “and” (left, right: integer ) return integer; 
function “and” (left, right: long_integer) return long_integer; 


An example of using package bit_ops with function and follows: 


with bit_ops; use bit_ops; 
procedure test_and is 


z: integer; 

begin ' 
z:8 0 and 0; -— 0 
x: 0 andl; - 0 
zim iland0; -— 0 
z:slandil; -1 
zim zr and 16#7F#; -~ get low-order seven bits 


end; 
18.4.2 Function “Or” 


The function or retums the bitwise “or” of its operands. 


function “or” (left, right: byte_integer) return byte_integer; 
function “or” (left, right: integer ) zeturn integer; 
function “or” (left, right: long_integer) return long_integer; 


An example of using package bit_ops with function or follows: 


with bit ops; use bit_ops; 
procedure test_or is 


z: integer; 
begin 

x :3 0 or O; -- 0 

z:=Q0ori; -1 

zr:e@lor0; — 1 

zx:szlori; -1 

zim ror 16%80% —- turn on eighth bit 
end; 


18.4.3 Function “Xor” . 


The function xox retums the bitwise exclusive-or of its operands. 


function “xor” (left, right: byte integer) return byte integer; 
function “xor” (left, right: integer ) return integer; 
function “xor” (left, right: long integer) return long_integer; 


An example of using package bit_ops with function xor follows: 
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with bit ops; 
procedure test_xor is 


use bit ops; 


z: integer; 

begin 

z :2 0 xor 0 -— 0 
z :s 0 xor 1 —i1 
zx :=i1xor 0; —1 
xz 3:1 xor 1 — 0 
zo:w rc xor 16$A5#; 
end; 


18.4.4 Function “Not” 


The function not retums the bitwise negation of its operands. 


function “not” (left: byte_integer) return byte_integer; 
function “not” (left: integer ) return integer; 
function “not” (left: long_integer) return long_integer; 


An example of using package bit_ops with function not follows: 


with bit ops; 
procedure test_not is 
byte_integer; 

integer; 
long_integer; 


rb: 
rw: 
zl: 
begin 


zb 
xb 


18.4.5 Function Shi 


not 
not 
not 
not 


ss not 
:= not 


0; 
1; 
0; 
0; 
1; 


use bit _ ops; 


— 164FFr# 
— 16#FEz# 


— 16$rrrrs 
——- 16#FFFE# 


—— 16$FFFF_FFrrt 
—— 16#FFFF_FIFE# 


The function sh1 performs a logical left shift of the Left operand by the number of bits specified in the 
xight operand. Note that right is always of type integer. 


function shl (left: byte_integer; right: integer) 
return byte integer; 

function shl(left: integer; right: integer) 
return integer; 

function shl(left: long_integer; right: integer) 
return long integer; 


An example of using package bit_ops with function sh1 follows: 
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with bit ops; use bit_ops; 
procedure test_shl is 


zw: integer; 
zl: long_integer; 

begin 
zw := shl(integer’ (1), 1); — 2 
rw := shl(integer’ (1), integer’size - 2); —— 16_384 
zw := shi (integer’ (1), 0); ~—1 
zl: shl (long integer’ (1), 1); — 2 
xl := shi (long integer’ (1), long_integer’size — 2); 

—- 1,073_741_824 

zl := shl(long_integer’ (1), 0); — i 

end; 


18.4.6 Function Shr 


The function shr performs a logical shift right of the Left operand by the number of bits specified in the 
right operand. Note that right is always of type integer. 


function shr (left: byte-integer;-- right: integer) 
return byte_integer; 

function shr(left: integer; right: integer) 
xeturn integer; 

function shr(left: long integer; right: integer) 
return long integer; 

An example of using package bit_ops with function shz follows: 

with bit_ops; use bit_ops; 

procedure test_shr is 
zw : integer; 
x1: long integer; 


begin 
zw := shr(integer’ (1), 1); -- 0 
rw := shr(integer’ (16#4000#), integer’size - 2); -- 1 
rw := shr(integer’ (1), 0); “1 
0 


zl := shr(long_integer’ (1), 1); == 


zl := shr(long_integer’ (16#4000_0000#) , long_integer’ size - 2); 
zl := shr(long_integer’ (1), 0); ie 
end; 
18.5 Package Math_Lib 
SPECIFICATION 


package math lib is 
pi: constant := 
3.14159 _26535_89793_2384 6_26433_83279 50288_41 972; 


e: constant := : 
2.7182 8 18284_59045_2353 6_02 874_71352_66249_77572; 
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function sin (x: float) return float; 

function cos (x: float) return float; 

function exp (x: float) return float; 

function sqrt (x: float) return float; 

function ln (x: float) return float; 

function atan(x: float) return float; 
end; 


USAGE 

The package math_1ib provides some useful transcendental functions as well as the constants pi and e 
given to forty decimal places. 

18.5.1 Function Sin 


The function sin retums the sine of its parameter, x, given in radians. 
function sin(x: float) return float; 
An example of using package math_1ib with function sin follows: 


with math lib; use math_lib; 
procedure test_sin is 

z: float; 
begin 

zr := sin(pi / 2.0); -— 1.0 
end; 


18.5.2 Function Cos 


The function cos retums the cosine of its parameter, 2, given in radians. 
function cos(x: float) return float; 
An example of using package math_1ib with function cos follows: 


with math lib; use math_lib; 
procedure test_cos is 

z: float; 
begin 

z := cos(pi / 2); ~-- 0.0 
end; 


18.5.3 Function Exp 


The function exp retums e raised to the power of its parameter, x. 
function exp(x: float) retura float; 
An example of using package math_1lib with function exp follows: 


with math lib; use math_1lib; 
procedure test_exp is 
z: float; 
begin 
zg := exp(0); -— 1.0 
end; 
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18.54 Function Sqrt 


The function sqxt retums the square root of its parameter, x. 
function sqrt (x: float) return float; 


An example of using package math_14b with function sqrt follows: 
with math lib; use math_1lib; 
procedure test_sqrt is 
2: L£loat; 
begin 
z 2m sqrt(2); -— 1.41421 ... 
end; 


18.5.5 Function Ln 


The function 1n returns the logarithm to base e of its parameter, x. 
function ln(x: float) return float; 
An example of using package math_1ib with function 1n follows: 


with math lib; use math_1lib;. 
procedure test_ln is { 
z: float; 
begin 
z:=iln(e); — 1.0 
end; 


18.5.6 Function Atan 


The function at an retums the arctangent of its parameter, x, given in radians. 
function atan(x: float) return float; 

An example of using package math_1ib with function atan follows: 
with math_lib; use math_1lib; 


procedure test_atan is 

zr: Lloat; 
begin 

zis 4 * atan(1); -— pi 
end; 


18.6 Package Spio 


SPECIFICATION i 


with text_io; 
package spio is 
procedure flush(file: in text_io.file type := 
text_io.current_output) ; 
end; : 


USAGE 


Package spio is intended for special manipulation of I/O run-time operations. ly, spo provides one 
function, £Lush, which does flushing for output text files. This is useful for displaying individual strings on 
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terminals without calling text_io.new_line. Files associated with terminal devices are line buffered, 
sO a put does not display anything until a newline is printed or the terminal output file (typically cur- 
rent_output) is flushed. Spo. £Lush is also useful in debugging to ensure that the maximum amount 
of text appears in an output file if a program is crashing mysteriously, and otherwise might not flush its last 
output to a file. 


Note that it is not necessary to use spi.o. flush to do same-line prompting for terminal input, when a get 
operation occurs on a terminal device, all output associated with the terminal device is flushed automatically. 


An example of using package spio follows: 


— This tests the spio.flush operation. 
with text_io; 
with spio; 
procedure flushit is 
type string _p is access string; 
type wordlist is array (natural range <>) of string_p; 
word: constant wordlist := ( 
new string’ (“This”), new string’ (“is”), 


new string’ (“a”), new string’ (“deliberately”), 
new string’ (“delayed”), new string’ (“sequence”), 
new string’ (“of”), new string’ (“words”), 

new string’ (”on”), new string’ (“a”), 

new string’ (“single”), new string’ (“line”), 

new string’ (”.”), new string’ (”.”), 


new string’ (”.”) 
); 
begin 
text_io.put_line(“This is an ordinary line of output”) ; 
for i in word’ zange loop 
text_io.put (word (4) .all); 
text_io.put (’ "); 
delay 0.5; 
spio. flush; 
end loop; 
text_io.put_line(”<done>”) ; 
end flushit; 


This example shows how spio. flush can be used to display individual words on a line with a time delay 
between each word. Note that when spio. flush is called with no parameter, it defaults to 
text_io.current_output. 


18.7 Package Spy 


SPECIFICATION 
with system; 


package spy is 
subtype byte is natural range 0..255; 


function peek (addr: system.address) return byte; 
procedure poke (value: byte; addx: system. address) ; 
end spy; - 
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USAGE 
Package spy is used to “spy” on memory locations or change their contents. 


Note that type spy . byte, as a subtype of natural, is not an cight-bit quantity; however, for peek and 
poke operations, it is the case that only eight—bit byte locations in memory are examined or modified. 


18.7.1 Function Peek 


Function peek retums the value of the eight-bit byte at the absolute memory location specified as addr. 
function peek (addr: system. address) return byte; . 
An example of using package spy with function peek follows: 
-- This tests peek and poke from the spy package 


with spy; 
with text_io; 
with system; 
procedure pptest is 
: character; 
b: spy.byte; 
v: constant spy.byte := 16#55#; 
package lio is new text_io.integer_io (system. address) ; 
package bio is new text_io.integer_io (spy .byte) ; 
begin 
spy. poke (value => v, addr => q’ address); 
text_io.put ("Poked “); 
bio. put (item => v, width => 0, base => 16); 
text_io.put(” into location ”); 
lio. put (item => q’ address, width => 0, base => 16); 
text_io.new_line; 


b := spy.peek(addr => q’ address) ; 
text_io.put ("Peeked %) ; 

bio.put (item => b, width => 0, base => 16); 
text_io.put(” from location ”); : 
lio.put (item => q’address, width => 0, base => 16); 
text_io.new line; 


if db = v then 
text_io.put_line ("PASSED") ; 
else 
text_io.put_line ("FAILED") ; 
end if; 
end pptest; 


18.7.2 Procedure Poke 


Procedure poke sets the value of the byte at memory location addr to the value specified. 
procedure poke(value: byte; addr: system. address) ; 
See the example of function peek for an example of how poke is used. 
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18.8 Package Text_Handler 


SPECIFICATION 


package text_handler is 
maximum: constant := integer’ last; 
subtype index is integer range 0 .. maximum; 


type text (maximum length: index) is limited private; 


function length(t: text) return index; 
function value (t: text) return string; 
function empty (t: text) return Boolean; 


function to_ text (s: string; max: index) return text; 
function to_text(c: character; max: index) return text; 
function to_text(s: string ) return text; 
function to_text(c: character ) return text; 
function “6” (left: text:. right :.. text ) xeturn text; 
function “&” (left: text; right: string >) xreturn text; 
function "&” (left: string; right: text ) yvreturn text; 
function “&” (left: text; right: character) return text; . 
function “&” (left: character; right: text ) xeturn text; 


fanction “=” (left: 
function “<” (left: 
function “<=” (left: 
function ">" (left: 
function “>=” (left: 


right: text) return boolean; 
right: text) return boolean; 
right: text) return boolean; 
right: text) return boolean; 
; gight: text) return boolean; 


Heats 


procedure set (object: in out text; value: in text); 
procedure set (object: in out text; value: in string) ; 
procedure set (object: in out text; value: in character) ; 


procedure append(tail: in text; to: in out text); 
procedure append(tail: in string; to: in out text); 
procedure append(tail: in character; to: in out text); 


procedure amend(object: in out text; 
by: in text; 
position: in index) ; 

procedure amend(object: in out text; 
by: in string; 

position: in index); 

procedure amend(object: in out text; 
by: in character; 
position: in index); 


function locate (fragment: text; within: text) return index; 
function locate (fragment: string; within: text) return index; 
function locate (fragment: character; within: text) return index; 
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private 
type text (maximum length: index) is 
record 


length: index := 0; 
value: string(1 .. maximum length) ; 
end record; 
end text_handler; 


USAGE 
The specification of package text. handles is taken from the LRM section 7.6. An object of type text 


mum length, representing the number of “valid” characters in the current text value. Any characters beyond 
the current length are undefined. The maximum possible length of a text object is integer’ last. 

Note that dealing directly with a string is not always quite as convenient as dealing with text, primarily 
because of the variable length aspect oftext. A string, whichis an unconstrained array, has a fixed length. 


18.8.1 Function Length 


Function length retums the current length of atext object. 
function length(t: text) return index; 
An example of using package text_handler with function Length follows: 
with text_handler; use text_handler; 
procedure test_length is 
t: text (10); 
1: index; 
begin 
set(t, “zasp”); 
1 := length(t); - 4 
end; 


18.8.2 Function Value 


Function value retums the string portion of a text object. 
function value(t: text) return string; 
An example of using package text_handler with function value follows: 


with text_handler; use text_handler; 
procedure test_value is 

t: text (10); 

gs: string (1. .4);. 


begin 

set(t, “rasp”); 

o(1..4) := value(t); —— ¢ mst contain exactly 4 characters 
end; F 


1 


18.8.3 Function Empty % : 


; : 7 : | 
Function empty retums true if the current dynamic length of its text parameter is 0, false otherwise. 
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function empty (t: text) return Boolean; 
An example of using package text_handler with function empty follows: 


with text_handler; use text_handler; 
with text_io; use text_io; 
procedure test_empty is 
t: text (10); 
begin 
set(t, “"); -- zero-length string 
if empty (t) then 
put_line(”"<empty>”) ; 
else 
put_line("t = “"” & value(t) & ‘”'); 
end if; 
end; 


18.8.4 Function To_Text 


The overloaded to_tezxt functions convert string or character objects to tezct objects. 
String to Text of Specified Size 
The first version of to_text converts a string to text, retuming a text value whose maximum size 
is max. 
function to_text (s: string; max: index) return text; 
Character to Text of Specified Size 
The second versionofto_text convertsacharacter totext, rtumingatext value whose maximum 
size is max. 
function to_text (c: character; max: index) return text; 
String to Text of Minimum Size 
The third version of to_text converts a string to text, retuming atext value whose maximum size 
is s’ length. 
function to_text(s: string) return text; 
Character to Text of Minimum Size 
The fourth version of to_text converts a character to text of maximum length 1. 
function to_text(c: character) return text; 


18.8.5 Function & 


The overloaded ”&” functions concatenate test. objects with other text objects, with strings, or with char- 
acters. A retumed text result has a maximum length that is the sum of the current dynamic lengths of its 
operands. 


function “6” (left: text; right: text 


) zveturn text; 
function “&” (left: text; right: string ) return text; 
function "&” (left: string; right: text ) xveturn text; 
function “&” (left: text; right: character) return text; 
function “&” (left: character; right: text ) zeturn text; 
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An example of using package text_handler with function & follows: 


with text_handler; use text_handler; 
procedure test_concat is 
t: text (80); 
begin 
set(t, “da”); 
set(t, t & t); = 
set(t, t & “esque”); —— “dadaesque” 
set(t, '_'’ & t); _ 
end; 


18.8.6 Relational Functions 


The relational functions for text objects are essentially the same as the equivalent functions for strings, ex- 
cept that the current dynamic lengths are taken into consideration. 


function “=” (left: text; right: text) return boolean; 
function "<"” (left: text; right: text) return boolean; 
function "<=" (left: text; right: text) return boolean; 
function “>” (left: text; right: text) return boolean; 
function ">=" (left: text; right: text) return boolean; 


Note that there is an implicit ”/=” function available as well. 
An example of using package text_handlex with relational functions follow. 


with text_handler; use text_handler; 
with text_io; use text_io; 
procedure test _relop is 
t, u: text (10); ; 
begin 
set(t, “there”); . 
set(u, “therapy”); i 
if t > u then 
put_line (*PASSED—— t > u”); 
else 
put_line("FAILED—- t <= u”); 
end if; 
end; 


18.8.7 Procedure Set 


The overloaded set procedures provide assignment operations for text objects. 
procedure set (object: in out text; value: in text ); 
procedure set (object: in out text; value: in string ); 
procedure set (object: in out text; value: in character); 


An example of using package text_handler with procedure set follows: 
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with text_handler; use text_handler; 
procedure test_set is 
t, u: text (10); , 
begin 
set(t, “zot”); 
set(t, '2'); 
set(u, t); 
end; 


18.88 Procedure Append 


The overloaded append procedures append string, text or character values to text objects. 


procedure append(tail: in text; to: in out text); 

procedure append(tail: in string; to: in out text); 

procedure append(tail: in character; to: in out text); 
An example of using package text _handler with procedure append follows: 


with text_handler; use text_handler; 
procedure test_append is 
t, u: text (10); 


append (u, to >t); -- “past” 

append(‘e’, to => t); -—- “paste” 

append(“urize”, to =>t)i — “pasteurize” 
end; 


18.89 Procedure Amend 


The overloaded amend procedures replace part ofa text object starting at a particular index position. These 
provide a facility similar to string slice assignment. Note that the first position in a text object is 1. 


procedure amend(object: in out text; 
by: in text; 


procedure amend (object: in out text; 
by: in string; 
position: in index) ; 

procedure amend (object: in out text; 
by: in character; 
position: in index); 
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An example of using package text_handlex with procedure amend follows: 


i with text_handler; use text_handler; 
procedure test_amend is 
t, u: text (10); 
begin 
_ 1234567 
set(t, “analogy”) ; 
set(u, “yst”) 


amend(t, by => u, position => 5); -- “analyst” 
amend(t, by => “ze”, position => 6); -- “analyze” 
amend(t, by => ’s’, position => 6); -- “analyse” 


end; 
18.8.10 Function Locate 
The overloaded Locate functions search for fragments (patterns) in text objects. Zero is retumed if an 


attempt to locate a fragment in a text. object fails. 


function locate (fragment: text; within: text) return index; 
function locate (fragment: string; within: text) return index; 
function locate (fragment: character; within: text) return index; . 


i An example of using package text_handler with function locate follows: 


with text_handler; use text_handler; 
procedure test_locate is 
t, wu: text (80); 


4: index; 
‘begin 
—_— 1 2 3 
-_ 12345678901234567890123456789012345 


set (t, “Beware the Lurker at the Threshold. *); 
set(u, “Cthulhu! ”) 


i := locate("Lurk”, within => t); -- 12 

i := locate('T’, within => t); -—— 26 

i := locate (u, within => t); -— 0 
end; 


18.8.11 Input-Output of Text 


Here are examples of input-output routines for text: 


with text_handler; use text handler; 
with text_io; use text_io; 
procedure put (t: text) is 
begin 
put_line (value (t)): 
end; 
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with text_handler; use text_handler; 
with text_io; use text_io; 
procedure get (t: in out text) is 

last: natural; 

8s: string(1. .t.maximum_length) ; 
begin 

get_line(s, last); 

set(t, s(1..last)); 
end; 
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Part IL Meridian Ada Command Reference 


Tus pat of he manual contains all Meridian Ada compiler commands in Spates 
order, Each command is listed along with its format, options if any, and examples 


where possible. 


Oe 
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ee 


The library management commands are described in this section, along with their invocation forms and their 
options. The commands are non-interactive, all necessary information is specified on the command line. 
An option for a command is specified as a letter preceded by a dash character (“—”). Options are separated 
from each other on the command line by a space character (“ "). An option may have more than one part: 
the sequence —x, where x is some letter, and an argument, separated from its preceding option letter x by a 
space. 
Note: Upper and lower case option letters mean different things. 
In the invocation forms shown, square brackets [ ] indicate optional information (not to be typed with literal 
brackets); italicized items indicate variable information; ellipses (‘*...”) indicate that the preceding item or 
items may be repeated indefinitely. For example: 

ada [option..] file.ada ... 


Here, ada is a command to be typed literally; option is some optional information that may be repeated; 
file.ada is file name information that may be repeated. : 
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A program library must be created using mk1Lib or newlib in advance of any compilation. The compiler 
aborts if it is unable to find a program library (either the default, ada. 1b, in the current working directory 
or the library name specified with the -Z. option). 


Note that the source file has the extension . ada. Just about any non-empty file extension is permitted. The 
ones not allowed include those used by the Meridian Adacompiling system for other purposes such as .obj 
for object module files. If an illegal ‘extension is given, the error message “missing OF improper 
file name” is displayed. Some other commonly used source file extensions are- 


.adb for package body source files 
.sub for subunit (separate) source files 


The Meridian Ada com iler emits native 80x86 object code. Determination of whether a program is to run 
Mn MT Mode or Extended Mode is made at link time, using the OAew option to select Extended Mode. 
See section 19.7 for a discussion of the bamp command. Programs that are to run only in Extended Mode, 
or that are to run in Real Mode only on 80286 or 80386 processors, may be compiled with the ada -£S. 
option to specify 80286-target code. 


19.1.3 Options 


~£p Generate debugging output. The -£D option causes the compiler to generate the appropriate code 
and data for operation with the Meridian Ada Debugger. For more information on using this option 
and using the Debugger, see Chapter 10. 


-fe Annotate assembly language listing. The -£e option causes the compiler to annotate an assembly 
language output file. The output is supplemented by comments containing the Ada source state- 
aaa responding to the assembly language code sections WrRES by the code generator. To use 

this option, the -S option must also be specified, otherwise the annotated file isnot emitted. Referto 
section 19.1.9 for more information. 


-£— Generate error log file. The -£& option causes the compiler to generate @ log file containing all the 
crrormessages and warming messages produced during compilation. The error log file has the same 
name asthe source file, with the extension .@xz. Forexample, the errorlog file for simple . ada is 

simple .err. The error log file is placed in the current working directory. In the absence of the 


eR _ Disable floating point checks. This option is used to 
sequences of math co-processor instructions, 


ada 


~fL 
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of this option means that the resulting program requires and i 

: » and you guarantee, the run-time presence of 
amath CO-processor (cither an 8087, 80287, or 80387). If a program containing floating point com- 
Putations is compiled with the -fF option, it will behave unpredictably if run on amachine without a 


Generate exception location information. The -£1 option causes location information (source file 
names and line numbers) to be maintained for intemal checks. This information is useful for debug- 
ging in the event that an “Exception never handled” Message appears when an exception propagates 


1. division_check 
2. overflow _check 


These checks are described in section 11.7 of the LRM. Using ~£ reduces the size of the code. Note 
that there is a related ada option, -£s to Suppress all checks for a compilation. See also section 3.5. 


The ~£Noption must be used in place of pragma suppress for the two numeric checks, because 

presently pragma suppress is not supported for division_check and overflow_check. Pragma 
suppress works for other checks, as described in section 2.4.2. In the absence of the -£N option, 

the numeric checks are always performed. 

Inhibit static initialization of variables. This option is intended for use in ROM-based embedded 

environments in conjunction with the Meridian Ada Run-Time Customization Library. The -£R 

option is applicable only in the presence of the -£s option, which suppresses certain runtime checks. 

Normally, the Ada compiler initializes constants or variables with Static data when the following con- 

ditions all occur: 

1. Checking is disabled with the -£8 option. 

2. The initializer expression is static (known at compile time). 

3. The object is a global (in top-level package specification or body). 

If the -£R option is specified, static initialization is suppressed for variables (but not for constants); 
assignments to each component of a variable are performed in the code. Note that this always happens 
in the absence of the -£s option. 

Suppress all checks. The -£s option suppresses all automatic checking, including numeric check- 
ing. This option is equivalent to using pragma suppress on all checks. This option reduces the 
size of the code, and is good for producing “production quality” code or for benchmarking the com- 

piler. Note that there is a related ada option, -£N to suppress only certain kinds of numeric checks. 

See also sections 2.4.2 and 3.5. 

The -£8 option causes the compiler to generate additional 80286 instructions not available on the 
8086/8088. Programs compiled in this mode tend to be smaller than programs compiled using the 
normal 8086/8088 mode. Nothing special is required to link programs compiled using this mode; the 
usual bamp command is used. Note that by default, programs are created to run in Real Mode. Ifthe 
bamp -x option is not used, the resulting program runs in Real Mode regardless of whether or not 
the program has been compiled with the -£8 option. The bamp —x option must be used to produce 
an Extended Mode program. 
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WARNING: 

Be certain that programs that run in Real Mode and that have been compiled for the 

80286 (or, more specifically, the individual modules that have been compiled for 

the 80286) are not run on 8086 or 8088-based systems, such as the original 13M 

PC, IBM PC-junior, IBM PC/XT, IBM PS/2-30 or similar compatible systems. 

Programs compiled for the 80286 will run oneither 80286 or 80386—based systems, 

such as the IBM PC/AT, IBM PS/2-60, IBM PS/2-80, Zenith Z-248, and similar 

compatible systems. 

Programs that run in Extended Mode will not run on on 8086 or 8088 based systems. 
Inhibit library update. The -£0 option inhibits library updates. This is of use in conjunction with the 
~8 option. Certain restrictions apply to the use of this option; see section 19.1.9. 
Compile verbosely. The compiler prints the name of each subprogram, package, or generic as itis 
compiled. Information about the symbol table space remaining following compilation of the named 
entity is also printed in the form “(nK]”. 
Suppress warning messages. With this option, the compiler does not print warming messages about 
eyed pragmas, exceptions that are certain tobe raised at run-time, oF other potential problems tat 
the compiler is otherwise forbidden to deem as errors by the LRM. 
‘The —g option instructs the compiler-to run an additional-optimization pass. The optimizer removes 
common sub-expressions, dead code and unnecessary jumps. It also does loop optimizations. This 


option is different from the -g option to bamp. The -g option to ada optimizes the specified unit 


when it is compiled; no inter—unit optimization is done. The ~g option to bamp analyzes and opti- 
mizes the entire program at link time. Note: Even if -g is specified for the ada command, the -K 
option to ada must still be specified for the —g option to bamp to be effective. 

Keep intemal form file. This option is used in conjunction with the Optimizer (see Chapter 7 for more 
information). Without this option, the compiler deletes internal form files following code genera- 
tion. 


—1modifiers 


Generate listing file. The -1 option causes the compiler to create alisting. Optional modifiers can be 
given to affect the listing format. You can use none or any combination of the following modifiers: 


c continuous listing format 

P obey pragma page directives 

s use standard output 

t relevant text output only 
The formats of and options for listings are discussed in section 19.1.7. The default listing file gener- 
ated has the same name as the source file, with the extension . 1st. For example, the default listing 
file produced for simple . adahas the name simple. 1st. The listing file is placed in the current 
working directory. Note: -1 also causes an error log file to be produced, as with the -£E option. 


-L library—name 


Default: ada .1ib 
Use altemate library. The -L option specifies an altemative name for the program library. 


Produce assembly code. Causes the code generator to produce an assembly language source file and 
to halt further processing. This option must be used cautiously; refer to section 19.1 9 for more infor- 


mation. 


Note: Options beginning with -£ canbe combined, asin““-f.sv.” This is equivalent to specifying the options 


y.¢.g. “-£s -fv.” Options beginning with -1 can be similarly combined or separated, as in 


“les” or“-1e -1s” (see section 19.1.7). 
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19.1.4 Compiler Output Files 


Files produced by compilations, other than listings and error logs, are: 
.asn files assembly language files (only when -S option used) 
-atr files interface description files 
-int files Meridian Intemal Form Files 
gan files generic description files; nn is a two-digit number — 
. ob} files object code files 
. sep files subunit environment description files 


Also produced are various intermediate files; these are usually deleted as a matter of course. You normally 
need not concem yourself with most of these output files with the exception of assembly language files. 


Output files are placed either in the current working directory or in the auxiliary directory, depending on the 
configuration of the program library (as determined by mk1ibornew1lib). The name of an auxiliary direc- 
tory associated with a program library can be determined by using the —h option to the 1s14b command. 


Supplementary files that may be produced by a compilation are: 
.exr files _error log files (only when -£E option used) 
-1st files listing files (only when -1 option used) 
These are discussed in section 19.1.7. 


19.1.5 Non—Local Compilations 


The compiler is able to compile files that reside in directories other than the current working directory. As 
always, a program library (typically ada . 14) must be present in the current working directory. All output 
files are placed in the current working directory or in the local auxiliary directory (ada . aux). 


19.1.6 Compile-Time Error Messages 


When syntactic or semantic errors are detected in the source code, the Meridian Ada compiler produces either 
error messages or waming messages. These messages are normally produced on the standard output stream. 
If the -£% option is given, these messages are written, instead, to an error log file. The error log file has the 
same name as the source file, with the extension . err. 

When error messages are printed, processing does not proceed beyond the first pass. No object code file is 
produced. Warning messages do not prevent further processing. Other passes (e.g. the code generator) may 
print error messages as well, but these are almost certain to be error messages related to problems intemal to 
the compiler itself, and should be reported to your distributor. 

Error messages have the form: 

“filename”, nn: English explanation of error [LRM Lm.nip) 


where filename is the name of the program source file in which the error was detected, nn is the specific line 
number in the source file where the error occurred, followed by an explanationn English of the error, and, 
when appropriate, a reference to the LRM. The LRM reference gives the chapter (/), section (m), subsection 


(n), and paragraph number (p). 
An example follows. 
“rt.ada”, 245: record component redeclared [LRM 3.7/3] 


Depending on the severity of the error, the Meridian Ada compiler may attempt to recover and continue com- 
piling the source code, or may terminate compilation immediately. 
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Warning messages have the form: 
“filename”, R: <<warning>> message 
An example warning message is shown below. 
“st.ada”, 297: <<waxning>> INLINE: pragma has no effect 
Error messages that begin with 
week Compiler Error 
are intemal compiler error messages. If any appear, they should be reported to Meridian Software Systems. 
All error messages and warning messages should be self-explanatory. 
19.1.7 Listings 


The compiler by default does not produce listings. The -1 option causes the compiler to produce both a 
listing file and an error log file. The -£E option causes the compiler to produce only an error log file. In the 
absence of these options, the compiler prints an error log to the standard output stream alone. 


Listing File Contents 
The listing file contains line-numbered, paginated source text with error messages and waming messages in- 
terspersed. Listing file error messages appear in the format: - 

x 


RRNEKE orror message 
* 


Waming messages appear in the format: 
+ 
+4+++4+0 warning message 
+ 
The listing generated when -1 is specified obeys pragma List and pragma page as described in the LRM. 
Pragma List and pragma page have no effect in the absence of the -1 option. 


Listing F ormat Control 


Listing format is controlled via modifiers to the -1 option or via a compiler default option description file 
named ada. ind. Refer to section 19.1.8 for information about the ada. ini file. 


The -1 option has the form —lmodifiers, where modifiers are zero or more of these letters: 


c Use continuous listing format. The listing by default contains a header on each page. Speci- 
fying -1c suppresses both pagination and header output, producing a continuous listing. 

P Obey pragma page directives. Specifying ~1p is only meaningful if -1c¢ has also been 
given. Normally -le suppresses all pagination, whereas ~1cp suppresses all pagination 
except where explicitly called for within the source file with a pragma page directive. 

s Use standard output. The listing by default is written to a file with the same name as the 
source file and the extension 1st, as in simple .ist from simple. ada. Specifying 
1 causes the listing file to be written to the standard output stream instead. This output 
may be redirected anywhere (e.g. to the PRN device). 

t Generate relevant text output only. The listing by default contains the entire source program _ 
as well as interspersed error messages and warning messages. Specifying -1t causes the 
compiler to list only the source lines to which error messages or waming messages apply, 
followed by the messages themselves. 
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Any, all or none of the suffix letters c, p, 8, and t may be given following -1, as in-1es, —lct, or-lest. 
The options can also be given separately, as in -1c ~1s8. 


19.1.8 Default Option Description File 


Compiler behavior can be modified not only by command line options, but also by a default option description 
file named ada. ini. Default options are given in paclib\ada. ini, while local overriding options can 
be given in an ada. in file in the current working directory. At present, only listing format parameters can 
be set in a compiler default option description file. 

The ada.ini file is an ordinary text file that may be created or edited with any editor used to edit Ada 
programs. The default paclib\ada.ini file contents are: 


—~ Meridian Ada compiler default option description file 


-~page_length :@ 66; — min: 5 
--top_margin . sm 6; — min: 2 
--bottom_margin 2s 6; ——- min: 2 
—~left_margin sm 4; -— min: 0 
——page_width :@ 132; —— min: 40 
—-lineno_width 2 5; —- min: 0 
~-marker_lines = 1; -- min: 0 
—-header_timestamp := true; 
——summary 2m true; 
--graphic_controls 2m true; 
—-error_tag 2m "RY; 
~-warning tag sw"; 


The paclib\ada. ind file as it is initially configured consists solely of comments showing examples of 
parameter assignments. The compiler default option description file may consist of Ada comments, blank 
lines, or assignments. In the example above, the initial comment characters (““——”) must be deleted to make 
any parameter assignment effective. The comments show the default values of the parameters, so there is no 
need to un-comment any particular assignment unless the value is to be changed. An example of a local 
ada .ini file might be: 


—- Local Meridian Ada compiler default option 
——- description file 


page_width := 79; 
— Use all other defaults. 


The parameters to which assignments can be made are: 


bottom_margin This parameter sets the number of lines in the bottom margin of each page. The bot- 
tommost lines are blank. The minimum number of bottom margin lines that can be 
specified is 2. The bottom margin is suppressed by using the -1¢ (continuous list- 
ing) option. 

error_tag This parameter specifies the character string that is displayed at the beginning of any 
error messages that occur in the listing. This string serves to highlight the errormes- 
sage. 
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graphic_controls This parameter determines how non-printable characters in the Ada source file 
are pri Non-printable characters include the ASCII DEL character and all 
ASCll control characters except for ASCII horizontal tab and the normal line termi- 
nator characters. If this parameter’s value is true, then the control characters are 
printed as “x where x is the printable character derived by adding the number 64 
(decimal) to the ASCII code value of the control character. Forexample, the ASCII 
BEL character, also known as Control-G (*G), is printed as “G. Other non-print- 
able characters are displayed as “?. If the parameter’s value is set to false, then the 
non-printable characters are displayed as is with no conversion. 


header_timestamp 

This parameter specifies whether the heading information should include the date 
and time when the listing was generated. If its value is true, then the date and time are 
displayed. If its value is false, no date or time is printed. 


left_margin This parameter specifies the number of blanks printed in each line before anything 
else (including line numbers, source lines, messages, and heading information). The 
left margin can be no smaller than 0 characters. 
lineno_width This parameter specifies the number of characters reserved for the line number that 
appears to the left of each source line listed. The line number width can be no smaller 
than 0 characters. If 0 is specified, no line numbers are generated. 


marker_lines This parameter specifies the number of marker lines to print before and after an 
error or waming message. Marker lines serve to make these messages stand out 
more from the rest of the listing. The minimum number of marker lines is 0. 
page_length This parameter sets the number of lines printed per page. A page ejectis placed at the 
end of each page. ‘The minimum number of lines that can be specified for the page is 
5. The page eject can be suppressed by using the ~1¢ (continuous listing) option. 
page_width This parameter specifies the number of characters in the longest line that will be 
printed before the line is broken to the next line. The page width cari be no smaller 
than 40 characters. This value does not include the number of characters specified 
by the left_margin and lineno_width parameters. 


summary This parameter specifies whether the listing should include a compilation summary 
at the end. Ifa summary is desired, this parameter’s value should be set to true, other- 
wise it should be set to false. 


top_margin This parameter sets the number of lines in the top margin of each page. Centered in 
the topmost lines of each page a heading is printed containing a page number, file 
name, and date. ‘The minimum number of top margin lines that can be specified is 2. 
The top margin and heading information can be suppressed altogether by using the 
—16 (continuous listing) option. 
warning tag This parameter specifies the character string that is displayed at the beginning of any 
warming messages that occur in the listing. This string serves to highlight the wam- 
ing message. 


19.1.9 Producing Assembly Code 


It is possible to produce human-readable assembly language output from a compilation by using the —S op- 
tion to ada. The assembly language output file is primarily used for reference purposes. The name of the 
assembly language output file must be determined by using the -1 option to Ls1ib. Refer to section 19.1.4 
for an explanation of the way file names are assigned. Note that the assembly language output file itself is 
placed in the auxiliary directory if the auxiliary directory is present 
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The —$ option must be used with care because of the way the compiler interacts with the library system. When 
an assembly language file is generated, but not assembled, the library is normally updated as though an object 
file has been produced. This means that the information in the library is incorrect with respect to the compila- 
tion unit until an object file is actually produced. If bamp is used prior to the creation of an actual object file, 
there will be unresolved symbols at link time. 


One way around this problem is to use the -£0 option. This inhibits library updates, but can be used only in 
certain circumstances. The —£0 option cannot be used in compilations where specifications and bodies are 
co-resident in a single file. This is because compilation of a specification generates library information that 
is then needed for compilation of the body. This means also that when a body is present for a specification, 
the specification cannot be compiled with the -£0 option. Ordinarily this is not a problem, because any code 
generated for a specification is replaced with the code generated for the body; the code for the body includes 
any code that would have been produced for the specification alone. 


Tosummarize, the -S option should be used only with the body; the specification should be in a separate file. 
When the body is compiled with the -8 option, the -£U option should be given as well. 


It is also possible to correct the library information problem by assembling the assembly language output file 
to produce an object file. The object file produced by an assembly should be placed in the same directory in 
which the assembly language source file is found. 


19.1.10 Examples 


Example 1 
Compile x . ada in the usual manner: 
ada x.ada 
Do not forget to type the extension. If you do not type the extension the ada program displays the error mes- 
sage “missing or improper file name”. : 
Example 2 
Compile x . ada with exception location maintenance code: 
ada -fL x.ada 
This is most useful when debugging a program that raises an exception. 
Example 3 
Compile x . ada, but with all automatic checking suppressed: 
ada -fs x.ada 
This is most useful after a program has been debugged and it is time to generate a “production” version of 
the program that is smaller and runs more quickly. 
Example 4 
Compile x. ada, but with numeric checking suppressed: 
ada -f8 x.ada 
This retains most of the useful checks, while speeding up the program and decreasing its size. 
Example 5 
Compile x. ada, y. ads, and x. adb in the usual manner: 
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ada x.ada y.ads z.adb 
Each source file is compiled in the order given. 


Example 6 . 
Compile 2. adb and produce an annotated assembly language listing: 
ada -feU -S x.adb 
Refer to section 19.1.9 for additional information about producing assembly language output. Note that the 
-fe ,-£0 , and -8 options typically must be used together. 
Example 7 
Compile 2. ada using an altemate program library named = . 14D: 
ada -L sz.lib x.ada 
This presumes that 2 .1..b was created in the current working directory with the miUb program Prior 
compilation. 
Example 8 
Compile x. ada verbosely, suppressing waming messages: 
ada -fvw x.ada 
For the fv option, the compiler prints the name of each subprogram, package, or generic as it is compiled, 
along with the amount of symbol table space remaining. For the -£w option, the compiler suppresses warning 
messages. 
Example 9 
Compile simple . ada, producing a listing file: 
ada -1 simple.ada 
This produces a listing file named simple. 1st and an error log file, simple .err. 


Example 10 
Compile simple. ada, producing a continuous-—form listing file on standard output: 
ada -lsc simple.ada 
This produces alisting on standard output in continuous format (no headers or pagination), as well as an error 
log file, simple.exrr. 
Example 11 
Compile simple. ada ina non-local directory, producing a local object file: 
ada e:\i\me\mine\sinple.ada 
Anada.14b file must be present in the current directory. All output files are placed in the current directory 
or in the local auxiliary directory (ada . aux). 
Example 12 
Compile simple . ada for the 80286: 
ada -fS simple.ada 
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Remember that a program compiled with this mode cannot be run on 8086/8088—based systems such as the 
original IBM PC, IBM PC-junior, IBM PC/XT, or IBM PS/2~30; the program does run on the IBM PC/AT, 
IBM PS/2-60, IBM PS/2--80, Zenith Z-248, and other compatible systems. 
Example 13 
Compile simple . ada running the local optimizer: 
ada -g simple.ada 
Runs an additional optimization pass during compilation. 
Example 14 
Compile simple. ada normally, but retain information for the global optimizer: 
ada -K simple.ada 


Runs the compiler normally, but does not delete simple. int, which can be used by a subsequent global 
optimization (bamp -—g) command. 
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19.2.2 Description 


ada program. The ada2 command is not needed if the Meridian Ada Extended Mode Com iler is used. 
(The Meridian Ada Extended Mode Compiler is available separately.) 


Ada2 supports all command options described for the ada command in section 19.1.3 except for —g and -8. 
Referto section 19.1 for additional information about command line options and general behavior of the com- 


piler. 

As with ada, a program library must be created using mk1ib or new1.ib in advance of any compilation. 
The compiler aborts if it is unable to find a program library (either the default in the current working directory 
or as specified with the -Z option). 


The ada2 command leaves a filenamed pacout .bat inthe current working directory. The pacout .bat 
file is a temporary batch file created by ada2 to which the ada2 command chains to perform the actual 
compilation. The pacout .bat file may be deleted following compilation. 


Note that DOS limits the number of command line arguments for batch commands to 9. The ada2 command 
ignores command line arguments after the ninth. 


19.2.3 Examples 


Example I 

Compile x . ada in the usual manner. 
ada2 x.ada 

Example 2 

Compile x. ada, y. ads, and x. adb in the usual manner: 
ada2 x.ada y.ads z.adb 

Each source file is compiled in the order given. 


157 Meridian Ada Compiler User’s Guide 


Meridian Ada Compiler User’s Guide 


158 


19.32 Description 


The adaext command reconfigures the compiler to run using extended memory, increasing its capacity, al- 
lowing much larger programs to be compiled. It also sets things up so that the ramp command can be run. 
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SERINE 


See 


The adarea command reconfigures the compiler after the adaext. command has been used to configure 
the compiler for using Extended Memory. This command undoes the effects of the adaext command. 
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19.5 amake 


19.5.1 Invocation 


19.5.2 Description 


The amake program is a tool that helps to speed software development by automatically invoking compila- 
tions and linkages when source files are modified or when recompilations are required by the rules of the Ada 
language. 


amake treats any file arguments as Ada source files which it compiles unconditionally, in the order given, 
before building the target(s). Amake distinguishes file from target only by the presence of a file extension 
in file (.g.count . ada). 


For each specified target compilation unit, amake examines the library information for source file informa- 
tion and dependencies. Any obsolete compilation units required by the target are compiled, followed by com- 
pilation of the target itself. A compilation unit is considered obsolete if its corresponding source file has been 
modified or if it has been rendered obsolete by a previous compilation. Once all compilation requirements 
have been satisfied, then linkage occurs, if the target is a main subprogram. 


If no target is specified, then amake selects the most recently compiled subprogram that fits the profile for 
a main subprogram (i.e. a parameterless procedure). 

A sequence of compilations initiated by amake halts iferrors occur during compilation. If dependencies (the 
sequences of WITHs for compilation units) are changed or ifnew dependencies are added, thenit is necessary 
to perform initial marwal compilations to introduce the new compilation units into the library. This can be 
accomplished by telling amake the new source files or the new compilation order with appropriate file argu- 
ments. Subsequent recompilations then can be done with amake. 

‘The amake program performs compilations and linkages only on units in the selected library (typically the 
- default local library, ada. 14b). If there are dependencies on obsolete units from non-local libraries, then 
amake complains and refuses to proceed. In that event, the non-local units must be brought up to date sepa- 
rately, possibly with an application of amake. 


Compilation and linkage options can be specified in an optional makefile, which is a text file named AMAKE . 
The amake -M option can be used to specify an altemative makefile name. 
A makefile contains lines that are comments, compilation options, or linkage options. A comment line begins 
with one of these character sequences: 

# 


A comment line can also be started with the keywords rem or remark. 


A compilation option line begins with the keyword compile followed by the name of a source file and then 
by a sequence of options to be given to the compiler if and when that file is compiled by amake. If the file 
name is a1, then any compilation options specified are applied to ail compilations. If the file name is oth- 
ers, then any compilation options specified are applied to compilations for which no options have otherwise 
been specified. Compilation options are cumulative. 


A linkage option line begins with the keyword Link followed by the name of a compilation unit and then 
by a sequence of options to be given to the linker (bamp) if and when that compilation unit is linked by 
amake. If the unit name is all, then any linkage options specified are applied to all linkages. If the unit 
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name is others, then any linkage options specified are applied to linkages for which no options have other- 
wise been specified. Linkage options are cumulative. 


An example of a makefile is: 
—— Example makefile 


— All files will be compiled with -K (keep internal 
-—- form files around for the optimizer) . 

compile all -K 

-- Suppress checks and generate a continuous listing 
-—- for xxx.ada. 


compile xxx.ada -fs -lc 
-- Generate exception location information when 
-~ compiling yyy.ada. 


compile yyy.ada -fL 


—- Perform global optimization when linking xxx. 


link xxx -G 


— Generate an extended mode program for yyy named “TEST .EXP” 


link yyy -x -o test 


This makefile causes -K to be applied in addition to the options given for specified files. For example, these 
operations would take place: 


ada -K -fs -lc xxx.ada 
ada -K -fL yyy.ada 
ada -K zzz.ada 

bamp -G xxx 

bamp -x -o test yyy 


Note that although there is no line for zzz . ada in the makefile, the -K option is applied, as specified for the 
all rule. 


19.5.3 Options 


These options can be applied to the amake command line. Options supplied in the makefile are given to the 
compiler or linker, and are otherwise ignored by amake. 


-c compiler-program—name 
Default: as stored in program library (ada. 1ib) 
The ~c option selects an alternative compiler. The default compiler used is the one stored in the pro- 
gram library. The —¢ option is intended primarily for use in cross—compiler configurations, although 
under such circumstances, an appropriate library configuration is nomnally used instead. 
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-fflags 
Default: none 
The —f option permits one to apply ada —£ options to the entire sequence of compilations invoked 
by amake. The list of -£ options available are as documented for the ada command. 
~-L. library-name 
Default: ada.1ib 
Use alternate library. The -L option specifies an altemative name for the program library. 
~M makefile 
Default: AMAKE 
The -¥M option selects an alternative makefile. 
-—a The =n option prevents the linkage step from occurring following any compilations. 
19.5.4 Examples 
Consider this sequence of compilation units which have already been compiled into the program library: 
In file mmm. ada: 
with text_io; 
procedure mma is 
begin 
text_io.put_line (“smm”) ; 
end mmm; 
In file xxx . ada: 


procedure xxx is 

procedure yyy is separate; 
begin 

yyy: 
end xxx; 


In file yyy . sub: 
with mmm; 


separate (xxx) 
procedure yyy is 


Example 1 
Following a modification of xxx. ada, apply amake: 
amake xxx 
This results in these compilations: 
ada xxx.ada 
ada yyy.sub 
bamp xxx 
The subunit yyy is recompiled because it becomes obsolete when its parent unit is recompiled. 
Example 2 
Following a modification of mam. ada, apply amake: 
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amake xxx 
This results in these compilations: 

ada mmm.ada 

ada yyy. sub 

bamp xxx 
The subunit yyy is recompiled because it becomes obsolete when the unit on which it depends, mmm, is recom- 
piled. 
Example 3 
Wihout any modifications, apply amake: 

amake mmm.ada 
This results in these compilations: 

ada mmm.ada 

bamp mmm 
The unit mmm is forcibly recompiled even though it has not been changed. The unit mmm is linked because 
mma. ada contains a subprogram that fits the profile fora main subprogram (i.e. a parameteriess procedure). 
When amake is not given an explicit target, it behaves like bamp with no target and causes the newest main 
subprogram to be linked. This behavior is particularly useful when compiling and linking small test programs 
that have not yet been entered in the library, or for forcing recompilations. 
Example 4 
Without any modifications, apply amake: 

amake mmm.ada xxx 
This results in these compilations: 

ada mmm.ada 

ada yyy.sub 

bamp xxx 
Now unit mmm is forcibly recompiled but 222 is the target to be remade. 
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19.6.1 Invocation 


19.6.2 Description 


The aug14b commandis used to attach additional link information to the library entry of a compilation unit. 
This command is primarily of use in conjunction with pragma interface (see Chapter 15). 

The kind of information that can be attached to a library entry by augl4b includes some linkage options and 
the names of non—Ada object files or code libraries. This information is used by baimp when it links the object 
file components of a program together. A subdle, but important point is that the information attached to ali- 
brary entry actually applies to the low-level object linker rather than to bamp. Although bamp looks up the 
information, it is not used directly by bamp. Instead, the information is passed by bamp to the low-level ob- 
ject linker. This means that only a limited set of bamp options (-o , —z , -V ) may be used with auglib, 
as these have direct analogs to object linker parameters. Most bamp options cannot be used to augment a 
library entry because those-options have no-meaning-to-the-low-level object linker. 


If the library—unit name is all, then any link-parameter specified with auglib applies to all object files 
linked via the bamp command. Note that the special name all recognized by auglib is a reserved word in 
Ada, thus there cannot be any confusion of this name with an existing library unit. The name all may appear 
in upper or lower or mixed alphabetic case. 


Information attached to a library unit with each subsequent aug1ib command accumulates; new informa- 
tion does not replace old information. If it is necessary to delete link information, the -x option should first 
be used to remove all previous information entered with auglib. 
The aug1ib command also provides some control over the linkage ordering of object modules. Object mod- 
ules are normally linked in a default order determined by bamp. Linkage ordering considerations are usually 
important only when dealing with object code libraries as opposed to individual object code files. The default 
linkage order, read from left to right, is: 

f,.0b} f2.0b} ... run-time 


where £; . ob files are object files corresponding to library units and run-time object libraries are linked last. 
This is essentially the syntax used by bamp when it invokes the low-level object linker. 

Note that bamp invokes the low-level object linker with syntax as modified by auglib. The effect of an 
auglib command can be tested by running bamp with the option -W and the name of the main procedure. 
The -¥ option to bamp causes the bamp program to print the commands executed in the course of a “dry run” 
without actually performing any linkage. 


19.6.3 Options 
-a Link after unit. The ~a option causes bamp to insert the link-parameter information just after the 
name of the object file corresponding to the library—unit. 


-b Link before unit. The -b option causes bamp to insert the link-parameter information just before the 
name of the object file corresponding to the library—unit. Note that this is the default case. 


-c “Connected” link syntax. The ~c option causes the bamp command to concatenate the link-para- 
meter information to the object file name, with no spaces between the two. This option is only in- 
tended for some unusual linkage situations not likely to occur on PC-DOS. 
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—d “Detached” link syntax. The -d option causes the bamp command to keep the link-parameter 
information separate from the object file name (no concatenation). Note that this is the default case. 

-e Link at end of list. The —e option causes bamp to insert the link-parameter information after all other 
object and run-time files to be linked by the bamp command. This option applies only to the all 
case. 


rary—name 

Default: ada .1ib 

Use alternate library. The -L option specifies the name of the program library to be used by the 
aug1ib program. This option overrides the default library name. 

-z _— Remove augment information. ‘The -z option causes any link information previously attached to a 
library unit with the aug] command to be disassociated with the specified library unit. This op- 
tion is useful if information must be changed or deleted. If the special library name a11 is used, the 
—r option just removes the link information associated with the all case; information associated 
with particular library units is untouched. 

19.6.4 Illegal Option Combinations 


The aug1ib options —a, —b, and —e are mutually exclusive. The —b option is actually the default and is 
sufficient for most cases. The ~e option applies.only if all is. specified as the library—unit. 

The —c and —d options are mutually exclusive. The —d option is the default. The —c option is intended for 
some unusual linkage situations that are not likely to occur on PC-DOS systems. 


19.6.5 Examples 


Example 1 
This is an example of a typical use of aug1ib in conjunction with pragma interface. 
Consider these compilation units: 

--Fictitious system clock interface: 


package clock is 
subtype time is long integer; 
procedure set_time(time_info: time); 
pragma interface (assembly, set_time) ; 
end clock; 


--Main procedure that calls clock interface: 
with clock; 


clock. set_time (1420); 
end clock_demo; 


In this example, an interface to an assembly language procedure called set_time corresponds to an Ada 
procedure, clock . set_time. 


To resolve the interface in package clock, itis necessary to cause the assembly language object code to be 
linked eventually with the main program when bamp is invoked on clock_demo. This is done by augment- 


ing the library entry of package clock with the name of the supplementary object file by using auglib. 
Assuming that the assembled code appears in an object file clk . obj, auglib is invoked as: 


auglib clock clk.obj 
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This command results in an augmented library entry for cLock, as shown in this long—format 1814 listing 
(see the “Augmented object” linc): / 
Package clock 
Source file name is “clkdemo.ada”. 
Internal link name is “clo”. 
Host system file name is “clock”. 
Entered on Wed Apr 15 1990 17:31:01 PST. 
Last changed on Wed Apr 15 1990 17:31:01 PST. 
No spec initialization 
Augmented object: clk.obj <obj> 
Ho es. 
Body is optional. 
Note that by augmenting the package in which the interf face declaration occurs, any program that makes use 
of package clock is linked appropriately. 
To link the program, bamp is simply run as usual on clock_demo: 
bamp clock demo 
The information augmenting the library entry for package clock is used automatically in the linkage. 


Example 2 
An example of using the —a option with all is: 
auglib -a all special.obj 


This command causes special. ob} to be linked after all of the Ada compilation unit object files, but be- 
fore the low-level Ada run-time object files. 


The corresponding linkage order is: 
f,.0bj f2.0bj ... special.obj run-time 
Example 3 


An example of using the -e option with al1 is: 
auglib -e all special.lib 
This command links the file special .14b after the low-level Ada run-time object files. 
The corresponding linkage order is: | 
f,.0bj £2.0bj ... run-time special.lib 
Example 4 
An example of using the —b option is: 
auglib -b clock clk.obj 
This command links the file clk . ocb4 before the object module corresponding to the library unit clock. 
The corresponding linkage order is: 
f,.0b} ... clk.obj clock.obj £,.0bj ... run-time 
Recall that -b is the default case. 


169 Meridian Ada Compiler User’s Guide 


auglib 


Example 5 
An example of using the —a option is: 
auglib -a clock clk.obj 
This command links the file clk. ob} after the object module corresponding to the library unit clock. 
The corresponding linkage order is: 
£,.0bj ... clock.obj clk.obj £,.cbj ... run-time 
Example 6 
An example of applying the bamp -V option permanently to a program is: 
auglib ginormous -V d:\tmpfile 


This causes the program ginormous to be linked always in “virtual mode” when bamp is run on it. The 
argument to ~V is just an example of a scratch file name to supply. This option is useful for linking large pro- 
grams that cause the low-level object linker to run out of memory. 


An important note for applying the -V option to the low-level object linker is that it must appear first, before 
any object files. This is the default case, but if other augment information is given, itis important to remember 
not to permit it to appear before the -V option. - - 
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19.7 bamp 


19.7.1 Invocation 


19.7.2 Description — 

The bamp (Build Ada Main Program) command creates an executable program given the name of the main 
subprogram. The main—procedure—name given to bamp must be a parameteriess procedure that has already 
been compiled. , 


Note: Be careful not to confuse the name of the source file containing the main subprogram (e.g. simn- 
ple. ada) with the actual name of the main subprogram (¢.g. simple). 


if'a main-procedure-name is not specified on the bamp command line, bamp links using the last-compiled 
subprogram that fits the profile for a main subprogram. To determine which subprogram will be used when 
no main subprogram is given to bamp, use the 1slib-t option. When in doubt, it may be best to specify 
the main subprogram explicitly. 

Note that when no main subprogram is specified, bamp selects the most recently compiled subprogram, not 
the most recently linked subprogram. If several different main subprograms are linked between compiles, 
still the most recently compiled subprogram is selected if no subprogram is explicitly specified. 

The bamp program functions as a high-level linker. It works by creating a top-level main program that con- 
tains all necessary context clauses and calls to package elaboration procedures. The main program is created 
as an intemal form file on which the code generator is run. Following this code generation pass, all the re- 
quired object files are linked. 

Unless the -x option is given, the bamp command produces a standard DOS Real Mode program. The -x 
option produces an Extended Mode program (see Chapter 11 for a discussion of Extended Mode Meridian 
Ada). 


An optional optimization pass can be invoked via the bamp command. The details of optimization are dis- 
cussed in Chapter 7. The bamp options relevant to optimization, -g and -G , are discussed below. 
Programs compiled in Debug mode (with the ada ~£D option) are automatically linked with the Meridian 
Ada source level debugger. 

19.7.3 Options 


-A _ Aggressively inline. This option instructs the optimizer to aggressively inline subprograms when 
used in addition to the -G option. Typically, this means that subprograms that are only called once are 
inlined. If only the —G option is used, only subprograms for which pragma inline has been speci- 
fied are inlined. 


-c compiler-program—name 
Default: As stored in program library. 


a Suppress main program generation step. The -£ option suppresses the creation and additional 
code generation steps for the temporary main program file. The -£ option can be used when a simple 
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-i 


-I 


change has been made to the body of a compilation unit. If unit elaboration order is changed, or if the 
specification of a unit is changed, or if new units are added, then this option should not be used. The 
—£ option saves a few seconds, but places an additional bookkeeping burden on you. The option 
should be avoided under most circumstances. Note that invoking bamp with the —n option followed 
by another invocation of bamp with the -f option has the same effect as an invocation of bamp with 
neither option (~n and —f neutralize each other). 


Perform global optimization only. The -g option causes bamp to invoke the global optimizer on 
your program. Compilation units to be optimized globally must have been compiled with the ada 
-K option. 

Perform global and local optimization. The -G option causes bamp to perform both global and local 
optimization on your program. This includes performing pragma inline. As with the -g option, 
compilation units to be optimized must have been compiled with the ada -K option. 

The —i option is used in conjunction with the bamp ~r option when producing “pre-linked” code 
foruse with the Intel Development Tools. The -4 option causes certain information to be emitted into 
the object file that is needed under some circumstances by the Intel linker, LINK8 6. By default, pre— 
linked object modules use the Microsoft object format. 


Link the program with a version of the tasking run-time which supports pre-emptive task scheduling. 
This option produces code which handles interrupts more quickly, but has a slight negative impact on 
performance in general. 


-L library-name 


Default: ada.1ib 


Use alternate library. The -L option specifies the name of the program library to be consulted by the 
bamp program. This option overrides the default library name. 


Produce link map. The —m option causes atext file containing a link map to be written. The link map 
is Microsoft-compatible and the link map file name has the extension . map for Real Mode programs 
(the default). For Extended Mode Programs (produced when the bamp —x option is given), the link 
map is OS/x86—compatible and the link map file name has the extension . xmp. 


—M main—program-—stack-size 


Default: 

e 20K in Real Mode programs 

e 64K in Extended Mode programs, when tasking is not used 

e 6AK-—<task-stack-size> in Extended Mode programs, when tasking is used 
Set main program stack size. ‘The -M option sets the stack size (number of decimal bytes) for the 
main program (excluding tasking). Note that the sum of the main program stack size and the tasking 
stack size must be no more than 64K bytes. 
No link. The —n option suppresses actual object file linkage, but creates and performs code genera- 
tion on the main program file. Note that invoking bamp with the —n option followed by another 
invocation of bamp with the -£ option has the same effect as an invocation of bamp with neither 
option. That is, ~n and -£ neutralize each other. 
No operations. The -™ option causes the bamp command todo a“dry run”; it prints out the actions it 
takes to generate the executable program, but does not actually perform those actions. The same kind 
of information is printed by the -P option. 


-o output-file-name 


Default: file.exe 
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Use alternate executable file output name. The -o 
gram file written by the bamp command. This option overrides the default output file name. 


Print operations. The —? option causes the bamp command to print out the actions it takes to gener- 


bamp 


option specifies the name of the executable pro- 


ate the executable program as the actions are performed. 

Create re-linkable output. The -z option causes an object file (. obj file) to be generated rather than 
anexecutable file ( . exe file). The resulting file contains all symbol and relocation information, and 
van thea be used with any low-level linker accepting object files compatible with the Intel or Micro- 


soft object formats. 


-s task~stack-size 


Default: 
e 20K if tasking used 
e Zero if tasking not used 


Use alternate tasking stack size. The —s option specifies the number of bytes (in decimal) to be allo- 
cated to all the tasks to be activated in the Ada program. This option overrides the default task stack 
size. Note that the sum of the main program stack size and the tasking stack size must be somewhat 
smaller than 64K bytes. The size of individual task activation stacks can be specified with a length 


clause, described in Chapter 6. 


Link software floating point library. Use of the -a option enables a program containing floating point 


computations to run with or without a math coprocessor chip. A related compiler option, the ada 
-£F option, also can be used to control the action of the run-time in the absence of amath co—proces- 
sorchip. The ada ~£¥ option and the bamp -u option should not both be used in the same program. 


Link verbosely. The -v option causes the bamp command to print out information about what ac- 
tions it takes in building the main program such as: 

© The name of the program library consulted. 

e The library search order (listed as “saves” of the library units used by the program). 

° The name of the main program file created (as opposed to the main procedure name). 

e The elaboration order. 

e The total program stack size. 

© Thename of the executable load module created. 

© The verbose code generation for the main program file. 


-V scratch-file 


Link using “virtual” mode. This option allows larger programs to be linked, although slightly more 
slowly. A scratch-file must be specified. The scratch-file can reside on a RAM disk (if one is avail- 
able) for faster operation. The -V option affects only the operation of the low-level object linker. The 
scratch-file is used’as scratch memory in which the various object files are ‘linked. 

Note: The -V option can be supplied once to auglib to make it a permanent effect for a program. 
An example of this is given in section 19.6. 


Suppress warnings. This option allows you to suppress wamings from the optimizer. 
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-x  The—zx option is used to create an Extended Mode program. This option applies only to Extended 
Mode Meridian Ada. The =x. option produces a program that can be run with the samp command to 
run in Extended Mode (a . exp file). Ifthe x option is not used, a Real Mode program (a . exe file) 
is produced. 

19.7.4 Examples 


Example 1 
Link main subprogram simp1e in the usual manner. 
bamp simple 
Example 2 
Link the most recently compiled main subprogram: 
bamp 
When no subprogram is specified, the bamp program displays the name of the library unit being linked as 
the main subprogram. Note that bamp selects the most recently compiled subprogram, not the most recently 
linked subprogram. 7 
Example 3 


Link main subprogram simp1e, creating an executable load module named simp . exe instead of sin- 
ple.exe: 


bamp simple -o simp 
Example 4 
bamp -f simple 
Bevery cautious in using the -£ option. The object file created by bamp corresponding to the main program 
is always named at . obj (“Ada top”). If bamp is invoked on another main subprogram (say, sieve, for 
example) then at . ob4 reflects the contents of the at .int file created and compiled for that program. If 
the -f£ option is subsequently used to link simple, then the wrong at .obj file is used in the object 
linkage. 
Example 5 
Link the main subprogram simple occurring in an alternate library, z.1lib: 

bamp -L z.1ib simple 


Example 6 
Link the main subprogram reschedule_demo using an altemate value for the main program stack size: 
bamp -M 10240 reschedule_demo : . 


This example specifies that 10K bytes are to be reserved for the main program stack instead of the default 20K. 
Note that this value does not affect the amount of space reserved for the task stack space, which is determined 
by the —s option. 


Example 7 
Link the main subprogram reschedule_demo using an alternate value for the total task stack space: 
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bamp —s 30720 reschedule_demo 


shin example specifies that 30K bytes ar wo be reserved for dhe toal task sack space instead oF etal 
20K. Note that this value does not affect the amount of space reserved for the main program stack. 


Do not use the -s option to set the amount of task stack space to zero when no tasking is used in a progm 
Do not ee  exermines tis lation suiomadcally and then reserves no additional stack space °F 
tasking. 
Example 8 
cink the main subprogram rescheduie_demousing alterate values forboth the total task stack space nd 
the main program stack space: 

bamp -s 30720 -M 10240 reschedule_demo 


This example reserves 30K for the task stack space and 10K for the main program stack space. Note that the 
ioral stack space (the sum ofthe task stack space and the main program stack space) reserved in this way pres- 
ently cannot exceed 64K. 


Example 9 
Create main program object file, at . obj, for the main subprogram simple but do not link the object files 
in the program: 
bamp -n simple 
Example 10 


Doa“dry run” of the linkage operations forthe main subprogram simp1e, printing out the system commands 
that would be used to perform the linkage: 


bamp -W simple 
This is useful to determine the linkage order of the various object files and object libraries in the program. 
The -® option can be used to “debug” auglib modifications. 
Example Il 
Link the main subprogram simple without creating an executable load module: 
bamp -r simple 
This option is useful for creating an object module to be linked with a different object linker (© the DOS 
system linker). The final object file created in this example is simple.ob}. 
Example 12 
Link the main subprogram simple verbosely: 
bamp -v sizple 
This prints out information about the elaboration process and the files created. 
Example 13 


Link the main subprogram eimpe, but print out the system commands used to do so as the commands are 
performed: 


bamp -P simple 
‘The information printed is the same as that printed for the -™ option. 
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Example 14 


Link the main subprogram simp1e using a different ada command with which to generate the main program 
object file (at . obj): 


bamp ~c c:\szada\bin\zada.exe simple 
The —c option is intended for use in cross~compiler configurations, although under such circumstances, an 
appropriate library configuration is normally used instead. 
Example 15 
bamp -V d:\tmpfile ginormous 
This is useful when a program becomes too large to link under nommal circumstances. Note that if drive d: 
is a RAM disk in this example, virtual mode linkage can go faster, however, the RAM disk must be large 
enough to accommodate all the object modules used to generate the executable load module. 
Example 16 
Link the main subprogram ginormous to produce an Extended Mode program: 
bamp -x ginormous 
This can be done only with Extended Mode Meridian Ada. The resulting unbound Extended Mode program, 
ginormou . exp, must be run with the ramp command. 
Example 17 
ink the main subprogram s4imp1e to produce a standard DOS Real Mode program, and produce a symbol 
map: ‘ 
bamp -m simple 
This produces a Real Mode map file, simple .map, and a Real Mode program, simple .exe. 
Example 18 
Link the main subprogram ginormous to produce an Extended Mode program, and produce a symbol map: 
bamp -m -x ginormous 


This can be done only if Extended Mode Meridian Ada has been installed. An Extended Mode map file, g3.- 
noxrmou . xmp, and an unbound Extended Mode program, ginormou . exp, are produced. The Extended 
Mode program must be run with the ramp command. The map file can be examined with the DOS type 
command. 
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19.8 help 


1982 Description 


rhe hep command provides heipfl hints and some troubleshooting information about the selected topic. | 
if no wopie is given on the command line, the help command displays the list of available topics. 
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19.9 Inlib 


19.9.1 Invocation 


19.9.2 Description 


The 1n1ib command adds library references, called links, to a program library. Once a program library has 
been created using mk14b, library references (inks) must normally be added using 1n1ib so that the stan- 
dard packages (e.g. text_io) may be introduced into compilations that use the new library. The new1ib 
Sar rd conmally adds default links so that explicit use of 1n14b is unnecessary except when building 
Each link added to a library is used in extended library searches by the compiler and by bamp (see Chapter 
8). 


The link-library-name given to Inlib should be a full file path specification. Relative directory specifica- 
tions, e.g. “.\” should not normally be used because searches through such links are performed relative to the 
current working directory. If the specified library is itself the target of further library linkages, any relative 
directory references change as the current working directory is changed. 


The 1n14b command can also un-link libraries from a program library if the —x option is used. 
The —k option to the Lg14b command can be used to list link entries. 


19.93 Options 


-L library-name 
Use altemate library. Default: ada.1ib 
The <1. option specifies an alternative name for the program library. 


Replace link. The option -z replaces ordeletes library links from a program library . Note that this is 
generally not a good idea because some library units can be left with dangling library references. Itis 
best to determine what library units depend on what other libraries (by using the 1slib command) 
before removing library links. 


The -r option changes the syntax of nib slightly so that only one or two library-name parame- 
ters are accepted on the command line (normally, Inlib takes an indefinite number of library name 
parameters). 


Note: Only link entries are affected by the ~x option; no program libraries are deleted. 
19.9.4 Examples 
Example 1 
Add a link entry into the program library: 
inlib c:\ada\paclib\ada.1lib 
A subsequent invocation of 1slib with the -k option prints any link entries; this might show: 
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Links to: 
c: \ada\paclib\ada.lib 


Example 2 
Add several link entries into the program library: 
linlib c:\ada\dosenv\ada.lib c:\ada\adautil\ada.1lib 
A listing of the resulting links might then show: 
Links to: 
c: \ada\adautil\ada.1lib 
c: \ada\dosenv\ada.1lib 
co: \ada\paclib\ada.1lib 
Example 3 
Remove a library link entry: 
inlib -r e:\ada\utils\ada.lib 
Example 4 
Replace a library link entry for e: \ada\utils\ada.1ib with e: \ada\adautil\ada.1lib: 
lnlib -—r e:\ada\utils\ada.lib e: \ada\adautil\ada.lib 
This deletes the link entry for e: \ada\utils\ada. lib. 
A subsequent run of 1s14b with the —k option mighit show: 
Links to: 
e: \ada\adautil\ada.lib 
e: \ada\paclib\ada.1lib 
Example 5 
Add a link entry to an altemate library, z . Lib: 
Inlib -L z.1ib c:\ada\paclib\ada.lib 


Example 6 
Delete a link entry from an altemate library, 2 . Lib: 
lnlib -L z.1ib -r e:\ada\utils\ada.lib 


Meridian Ada Compiler User’s Guide 180 


19.10 Islib 


19.10.1 Invocation 


19.10.2 Description 


The 181.4% command prints information about the contents of a program library or about a particular eniry 
for a compilation unit in the library. 


When invoked without options, 1s14b simply lists the units in the default program library. 
in onder for any Groupware information to be Listed, the program library (default or via ~1. option) must De 8 
Groupware library. 


19.10.3 Options 


-a__Listall, short. List the “immediate” library sub-tree used in context lookups by the compiler (to two 
levels). This option is normally given alone; if a unit-name is also specified, then only information 
about that comipilation unit is displayed. 

-a__Listall, long. List entire library graph (to indefinite levels). This option is normally given alone; ifa 
sanit-ncme is also specified, then only information about that compilation unit is displayed. 

-d unit 

List dependencies. List all units on which unit depends (i.c. everything that appears in a context 

clause (with clause) of the specified unit). This applies only to dependencies on compilation units in 

the default or specified library. 


-h _List “header” information. Information listed includes: 
© library internal name string (Groupware only) 
© library documentation string (Groupware only) 
e library version stamp 
e target machine type 
© library creation time (and creating user/group name (Groupware only)) 
e last library update time (and updating user/group name (Groupware only)) 
e library lock time and locking user/group name, if locked (Groupware only) 
e last unique link symbol generated 
e last unique file name generated 
e default compiler name 
e auxiliary directory name (if any) 
e archive name (if any) 
© optons 
-k _List link entries: The —k option lists all link entries in the default or specified library. 
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-1 Long-—format listing. Information listed includes: 
e source file name 
e library entry time (and entering user/group name (Groupware only)) 
e library update time (and updating user/group name (Groupware only)) 
e list of dependencies 
This option is equivalent to specifying —o with all modifiers. 
-1, library-name 
Use alternate library. Default: ada.lib 
The <1 option specifies an altemative name for the program library. 
—o modifiers 
Additional information listing, as specified by one or more of the following modifiers (the modifiers 
must be separated from —o by at least one blank): 
b Indicates if the body is defined and information about subunits, if any. 
d Lists dependencies. 
£2 Lists source file name. 
4 Lists mapping from programmer-—assigned name to unique link symbol and unique base file 
name. 


Lists unit type (subprogram, main subprogram, package, or task body), an indication if the unit is 
obsolete (needs recompilation), an indication if the unit uses tasking or initialization code, an in- 
dication if the unit uses debugging code, and any link options which may have been added to an 
entry using auglib. 
t Lists library entry time (and entering user/group name (Groupware only)) and library update time 
(and updating user/group name (Groupware only)). 
—t List in reverse time order. List units in order from most recent to least recent time of modification (or 
entry into the library). 
—w unit List dependents. List everything that depends on the specified unit (i.e. everything that names unit in 
a context clause). 
Options to the 1s14b program can be combined, as in -hk1. This is equivalent to specifying the options 
separately, e.g.“-h -k -1”. 


19.10.4 Examples 


Example 1 
List the compilation unit entries in the program library: 
islib 
This invocation of 1814b might produce a listing like: 
Package clock 
Subprogram clock_demo 
Package direct _int io 
Subprogram file form demo 


Package io example 
Subprogram zeschedule_demo 
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Example 2 

List the information in long format for a particular compilation unit entry: 
1slib -1 reschedule_demo 

This invocation of 1s14b might produce a listing like: 


Subprogram reschedule_demo 
Source file name is “td.ada”. 
Entered on Tue Apr 14 1987 12:39:55 PST. 
Changed on Tue Apr 14 1987 16:26:18 PST. 


Dependent on: text_io 
Example 3 | 
List the link entries (as well as the compilation unit entries): 
islib -k 
This invocation of 1s14b might produce a listing like: 


Links to: 
c: \ada\adautil\ada.lib 
c:\ada\paclib\ada.1lib 


Package clock 
Subprogram clock_demo 
Package direct_int_io 
@ Subprogram file_form_demo 
Package io example 
Subprogram reschedule_demo 
Example 4 
List all units on which text_io depends: 
lslib -d text_io 
The result of this invocation of 1s1ib is: 
Package io exceptions 
Package tcd_runtime 
Example 5 . 
List all units depending on example package clock: 
1slib -w clock 
The result of this invocation of 1s14b is: 
Subprogram clock_demo 
Example 6 
List all units in an alternate library: 
1slib -L c:\ada\paclib\ada.lib 
This is an example of listing the contents of the distribution library. Note that your distribution library might 
be elsewhere. 


| 
: 
: 
: 
: 
i 
i 
j 
| 
| 
| 
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This is likely to display something very similar to: 
Package ada_io 
Package calendar 
Package dcd_ runtime 
Generic Package direct_io 
Package enum _io runtime 
Package file manage 
Package fio 
Package fixed io runtime 
Package float_io runtime 
Package iio 
Package int _io runtime 
Package io exceptions 
Package machine code 
Package num _io runtime 
Generic Package sequential io 
Package syerr 
Package syio 
Package system 
Package sytime 
Package task control 
Package tcd_runtime 
Package terminate_runtime 
Package text_io 
Package tioc runtime 


Example 6 
List the library header: 


lslib -h 
In this example you can see the information displayed by a Groupware version of 1s814b. Note that the library 
has been locked in this particular case and that there is a documentation string (lslib examples) present. 


ada.1lib: 
lslib examples 


Library version 10. 

Generated for target 18086 msdos. 

Library created on Thu Aug 31 1989 17:14:32 by <gordon, r&éd>. 
Library updated on Fri Sep 15 1989 15:10:48 by <bill, réd>. 
Library locked on Fri Sep 15 1989 18:11:08 by <gordon, r&éd>. 
Last linker name used “aaaaaaaa”. 

Last file name used “aaaaaaaa”. 

Default compiler name “c:\ada\bin\ada.exe”. 

Config file “c:\ada\paclib\intel.cfg”. 

Aux file directory name “ada.aux\”. 


Example 7 
List additional information: 
1slib -o bim reschedule_demo 
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This invocation of 1s1ib produces a listing of information that is not available in the -L option, as follows: 
Subprogram reschedule_demo 

Internal linkname is “veschedu”. 

Host system file name is “reschedu”. 

Can be main program. 

Uses tasking 

Dependent on: text_io 
Body is defined. 
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19.11 mklib 


19.11.1 Invocation 


19.11.2 Description 


The mk1ib command creates a new program library. When options are not specified, all the defaults de- 
scribed below apply. Some caution is required when using mk1ib because it is possible to create libraries 
that supply completely nonsensical information to the compiler or the linker (e.g. a non-existent auxiliary 
directory, an incorrect compilation command, etc.). 

Note that the new14ib command is normally the first resort, it is usually unnecessary to use mk1ib except 
when building complicated programming project directories. 


Once a program library has been created using mk1ib, library references (links) must normally be added 
using 1n1ib so that the standard packages (e.g. text_io) canbe introduced into compilations that use 
the newly-created library. The newlib command adds some default links. 


To summarize, the steps involved in building a program library with mk1ib are: 


1. Create the auxiliary directory (if one is to be specified with the mklib command) using the 
mkdir command. 


2. Create the library using mklib. 
3. Enter into the library any desired library links using Ln1ib. 
19.11.3 Options 


a auxiliary—directory\ 
Default: None (current working directory). 
Name auxiliary directory. The specified auxiliary directory is to be associated with the created pro- 
gram library. All object files, interface description files, and other files created by compilations re- 
lated to the library are to be kept in the auxiliary directory. The mk1ib command does not automati- 
cally create the auxiliary directory, it must either exist or be created with the PC-DOS mkdir 
command prior to the first compilation involving the library. 
Note: The auxiliary directory name must be terminated with a slash (‘\’). 
-c compiler-program—name 
Default: ada 
Name compiler. The ~c option specifies the name of the Meridian Ada compiler. This information is 
saved in the program library sa that the bamp command can find the appropriate compiler to use. 
= library-name 
Default: ada.1ib 
Use altemate library. The -%. option specifies an alternative name for the program library. If an 
altemative name is given, all operations involving the library (including compilation) must specify 
thatname. Normally, only one program library can exist in a single directory, unless a separate auxil- 
iary directory is associated with each co-resident library. 
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19.11.4 Examples 


Example I 

Create a library with the default name and for the default target, but with no auxiliary directory: 
mklib -c c: \ada\bin\ada.exe 

Note that this example assumes the installation directory was c: \ada. 

Example 2 

Create a library with the default name, for the default target, with an auxiliary directory: 
mklib -c c:\ada\bin\ada.exe -a ada.aux\ 


Note that this example assumes that the installation directory was c: \ada. Please note the terminating slash 
(“\’) on the name of the auxiliary directory. The slash is required; otherwise, the compiler and bamp build 
incorrect path names for associated files. 


Recall that mk1ib does not create the auxiliary directory; that must be done separately with: 
mkdir ada. aux 

Example 3 

Create a library with an alternate name, for the default target, with an auxiliary directory: 
mklib -L z.lib -c c:\ada\bin\ada.exe -a z.aux\ 


Note that this example assumes that the installation directory was c: \ada. Also note the terminating slash 
(‘\"”) on the name of the auxiliary directory. The slash is required; otherwise, the compiler and bamp build 
incorrect path names for associated files. 


Recall that mk1ib does not create the auxiliary directory; that must be done separately with: 
mkdir z.aux 


All Meridian Ada library commands (including ada) that need to reference this library must do so explicitly, 
all commands use the same -L option for this. Forexample, to compile simple . ada using z . 1ib instead 
of ada. 1b, this command would be given: 


ada -L z.lib simple.ada 

An example of a subsequent 1814b command using x . Lib is: 
1slib -L z.1lib 

This 181ib command would display: 
Subprogram simple 
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19.12 modlib 


19.12.1 Invocation 


19.12.2 Description 


The mod. command can be used to help manage a programming project's libraries. With it you can arbi- 
trarily lock a library against update or insert additional documentation information in the library header. 


Note: This is a Groupware feature. 
19.12.3 Options 


—d string 
Change the internal documentation string. Up to 255 characters can be placed in the library header 
and is displayed immediately below the library name when the header is listed. To remove it simply 
change it to a null (empty) string. 


-1 Lock the library. When the library is locked it cannot be used as a program library by the compiler, 
ada. However, bamp can still build programs from a locked library and the library utilities can still be 
used to modify a locked library. The header contains the name and group of the user (ifavailable) that 
locked the library and can be displayed using 1slib —h. Note that this lock is independent of the 
library sharing mechanism built into Groupware. 

~L library-name 
Default: ada .1ib 
Use altemate library. The -1 option specifies the name of the program library upon which the mod- 
14> command is to operate. This option overrides the default library name. 

=n string 
Change the intemal library name. Aname of up to 255 characters can be placed in the library header. 
This internal name is for information only and cannot be specified as the library name for a—L option. 
It is displayed in place of the extemal name when the header is listed. To default to the external name 
simply change the internal name back to a null (empty) string. 


-ua Unlock the library. This restores the library to its original (unlocked) status. The ability to unlock the 
library is not restricted to the user that locked it. 
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19.13 newlib 


19.13.1 Invocation 


19.13.2 Description 


The new!.ib command creates a program library in the current working directory with the following useful 
default characteristics: 


e the default name, ada.1ib 
© an auxiliary directory named ada. aux 
© the default compiler name 


in addition to these default characteristics, a library link is established to the standard library area so that the 
standard units (e.g. text_4o) can be used in compilations. Also, the auxiliary directory, ada. aux, is 
created. Finally, new1ib lists the contents of the newly created program library. 


The new1ib program is actually a command file that can be modified to create libraries with any appropriate 
defaults. Normally, new14b is modified at installation time to conform to any site—dependent defaults. For 
example, 1n1ib commands are added to newlib .bat for any standard packages installed on the system, 
such as the DOS Environment Library or the Meridian Ada Utility Library. 
The mk14b and lnlib programs should be used when building libraries with any unusual requirements. 
Output from new1ib looks something like this: 

ada.1lib: 

Library version 9. 

Generated for target 18086. 

Last updated on Wed Apr 15 1989 17:31:02 PST. 

Last linker name used “aaa”. 

Last file name used “aaaaaaaa”. 

Default compiler name “c: \ada\bin\ada.exe”. 

Aux file directory name “ada.aux\”. 


Links to: 
c: \ada\paclib\ada. aux 
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19.14 ramp 


19.14.1 Invocation 


19.14.2 Description 


‘The xamp program is used to run unbound Extended Mode Meridian Ada programs. The command form 
for running an Extended Mode program with ramp is identical to that for running a Real Mode program, ex- 
cept that xamp precedes the rest of the command line: 


ramp program-name [options...] [1/O-redirections] 


The program-nameis the name of an Extended Mode program that can be found anywhere in the DOS search 
path (the search path is shown with the DOS path command). Options are whatever command line options 
apply to the Extended Mode program to be run. 1/O-redirections are standard DOS command line I/O redi- 
rections. Examples are given below. 


If necessary, the ramp command may be hidden by use of DOS batch (. bat) files or eliminated entirely by 
an Extended Mode program with the separately available bind program. A brief discussion of the 
bind program is given in section 11.4.3. 


Before the amp program is used to load and run an Extended Mode program the adaext program must 
be run to properly set up the Extended Mode environment. 
19.143 Files Used by Ramp 


Extended Mode Meridian Ada program files that are run by zamp have the extension . exp. Real Mode Me- 
ridian Ada program files have the extension . exe. Both kinds of programs are produced as the final products 
of the bamp command. The bamp -x option is used to produce Extended Mode programs with the .exp 
extension. 


19.14.4 Examples 


Example 1 
Run an Extended Mode program: 
zamp extp 


This example searches for a program file named ext p . exp anywhere in the DOS command search path and 
_ runs the program in Extended Mode. , 


Example 2 
Run an Extended Mode program with command line arguments: 
zamp extp -o file.out 


This example runs the program filenamed extp . exp with command line arguments that apply to the ext p 
program. 


Example 3 
Run an Extended Mode program with output redirection: 
ramp extp > PRN 
This example runs the program file named extp . exp and redirects the output to the printer. 
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19.15 rmlib 


19.15.1 Invocation 


19.15.2 Description 


The rmlib command deletes alibrary unit entry from the specified program library. When an entry has been 
removed from a program library, all files associated with that library unit are deleted (object file, interface 
description file, etc.), except for the source file. Source files (. ada files) are never deleted by xml ib. 
The rmLib command does not permit units to be deleted arbitrarily. A unit entry cannot be deleted if other 
units depend on it. By deleting or appropriately updating the entries for other dependent units, it becomes 
possible to delete an entry. For example, if unit a withs b, the entry for unit b cannot be removed unless the 
entry for a is first deleted or updated after deleting the context clause for b. 


19.15.3 Options 


-a Remove all. The -a option deletes all compilation unit entries in the library, but leaves the library 
intact. Link entries are preserved. When the -a option is used, no unit-name parameter should be 


given. 

-b Remove body information. The -b option deletes only information about the body of the unit, not 
information about the specification. 

-L library—name 


Default: ada.1ib 


Use alternate library. The -L option specifies the name of the program library upon which the 
zml1ib program is to operate. This option overrides the default library name. 


-r Remove “recursively”. The -x option deletes all local entries on which the unit depends as well as 
the unit entry itself. Only entries inthe local library are affected; libraries with link entries in the local 
library are unaffected (e.g. text_io does not disappear when —z is used). 


-v _ Remove verbosely. The —v option lists each file related to the library entry as the file is deleted. 

19.15.4 Examples 

Example 1 

Delete the entry for unit simple: 
zmlib simple 

Example 2 

Delete all entries verbosely, leaving the library otherwise intact: 
zrmlib -a -v 

Example 3 

Delete the entry for unit simple from a different library: 
rmlib -L c:\ada\test\ada.lib simple 
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Example 4 


Delete information about the body of unit simp1e, leaving information about the specification of simple -) 


zmlib -b simple 
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ppendix F Implementation—-Dependent Characteristics 


————————— 


This appendix lists im sementation-dependent characteristics of Meridian Ada. Note that there are no pre- 
ceding appendices. This appendix is called Appendix F in order to comply with the Reference Manual for 
the Ada Programming Language* (LRM) ANSI/MIL-STD-1815A which states that this appendix be named 
Appendix F. 

Implemented Chapter 13 features include length clauses, enumeration representation clauses, record repre- 


sentation clauses, address clauses, interrupts, package system, machine code insertions, pragma inter- 


The implemented pre-defined pragmas are: 


list See the LRM Appendix B. 
pack See section F.1.2. 


page 

priority Scethe LRM Appendix B. 

suppress Sce section F.1.3. 

inline See the LRM section 6.3.2. This pragma is not actually effective unless you compile/link 
your program using the global optimizer. 


The remaining pre-defined pragmas are accepted, but presently ignored: 


controlled optimize system name 
shared storage_unit 
memory size 


Named parameter notation for pragmas is not supported. 


When illegal parameter forms are encountered at compile time, the compiler issues a waming message rather 
Meee required by the Ada language definition. Refer to the LRM Appendix B for additional intor- 
mation about the pre-defined pragmas. 


F1.1 Pragma Interface 


The form of pragma interface inMeridian Ada is: 
pragma interface ( language, subprogram [, “link-name”} ); 
where: 


language Thisis the interface language, one of the names assembly, builtin, c, microsoft_c, or inter- 
nal. The names builtin and internal are reserved for use by Meridian compiler maintainers 
in run-time support packages. 
subprogram This is the name of a subprogram to which the pragma interface applies. 


eS 
*All future references to the Reference Manual for the Ada Programming Language appear as the LRM. 
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link-name Thisis an optional string literal specifying the name of the non-A da subpro, 
: gram correspond- 
ing to the Ada subprogram named in the second parameter. If link-name is omitted, then 
link-name defaults to the value of subprogram. Depending on the language specified, some 
automatic modifications may be made to the link—name to produce the actual object code 
symbol name that is generated whenever references are made to the corresponding Ada sub- 
program. The object code symbol generated for link—name is always translated to uppercase. 
Although the Meridian object linker is case-sensitive, it is a rare object module that contains 
mixed-case symbols; at present, all Meridian 80x86 object modules use upper case only. 
It is appropriate to use the optional link-name parameter to pragma intexface only when 
the interface subprogram has a name that does not correspond at all to its Ada identifier or 
when the interface subprogram name cannot be given using rules for constructing Ada identi- 
fiers (e.g. if the name contains a ‘$’ character). 

The characteristics of object code symbols generated for each interface language are: 

assembly The object code symbol is the same as link—name. 

builtin The object code symbol is the same as link-name, but prefixed with two underscore charac- 
ters (“__”). This language interface is reserved for special interfaces defined by Meridian 
Software Systems, Inc. The builtin interface is presently used to declare certain low-level 
run-time operations whose names must not conflict with programmer-—defined or language 


system defined names. 
c The object code symbol is the same as link-name, but with one underscore character (*_’) 
prepended. This is the convention used by the C compiler. : 
internal No object code symbol is generated for an internal language interface; this language inter- 


face is reserved for special interfaces defined by Meridian Software Systems, Inc. The inter- 
nal interface is presently used to declare certain machine-level bit operations. 
microsoft_c The object code symbol is the same as link—name, but with one underscore character (*_’) 
prepended. This is the convention used by the Microsoft C compiler. 
The low-level calling conventions are changed only in the case of a microsoft_c interface. No automatic data 
conversions are performed on parameters of any interface subprograms. It is up to the programmer to ensure 
that calling conventions match and that any necessary data conversions take place when calling interface sub- 
programs. 
A pragma interface may appear within the same declarative part as the subprogram to which the pragma 
interface applies, following the subprogram declaration, and prior to the first use of the subprogram. A 
pragma interface that applies to a subprogram declared in a package specification must occur within the 
same package specification as the subprogram declaration; the pragma interface may not appear in the 
package body in this case. A pragma interface declaration for either a private or nonprivate subprogram 
declaration may appear in the private part of a package specification. 
Pragma interface for library units is not supported. 
Refer to the LRM section 13.9 for additional information about pragma interface. 


F.1.2  Pragma Pack 


Pragma pack is implemented for composite types (records and arrays). 

Pragma pack is permitted following the composite type declaration to which it applies, provided that the 
pragma occurs within the same declarative part as the composite type declaration, before any objects or com- 
ponents of the composite type are declared. 

Note that the declarative part restriction means that the type declaration and accompanying pragma pack 
cannot be split across a package specification and body. 
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The effect of pragma pack is to minimize storage consumption by discrete component type whose ranges 
permit packing. Fr Pa muapack does not defeat allocations of alignment storage gaps for some Tome. 
types. Pragma pack eae apfect the representations of real types, pre-defined integer types, and access 


F13 Pragma Suppress 


Pragma suppress is implemented as described in the LRM section 11.7, with these differences: 


e Presently, division_check andoverflow_check must be suppressed via a compiler 
flag, -£N ; pragma suppress is ignored for these two numeric checks. 


© Theoptional “ow =>” parameter name notation for pragma suppress is ignored. 
e The optional second parameter to pragma suppzess isignored; the pragma always 
applies to the entire scope in which it appears. 
F.2 Attributes 


All attributes described in the LRM Appendix A are supported. The implementation-dependent Meridian 
attribute " Locof£set is applied to a parameter and retums as a universal—integer the stack offset of that 
parameter (the offset from the BP register)- It allows machine code insertions to access parameters using less 
error-prone symbolic names. An example follows. 2 


machine code. inst3’ (1648B#, 16#4E#, nbytes’ locoffset) ; 
E3 Standard Types 
Additional standard types are defined in Meridian Ada: 
e byte_integer 
e short_integer 
e long_integer 
The standard numeric types are defined as: 
type byte_integer is range -128 .. 127; 


type short_integer is range -32768 .. 32767; 
type integer is range -32768 .. 32767; 
type long_integer is range 2147483648 .. 2147483647; 


type float is digits 15 
range -1.797693134862318+308_ .. 1.79769313486231E+308; 


type duration is delta 0.0001 range -86400.0000 .. 86400.0000; 
F4_ Package System 


The specification of package system is: 


package system is 
type address is new long_integer; 


type name is (18086) ; 
system_name : constant name :* 18086; 
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storage unit : constant := 8; 
memory size =: constant := 1024; 


— System-Dependent Named Numbers 


min int : Constant := -2147483648; 
max_int : constant := 2147483647; 
max digits : constant := 15; 

max_ mantissa : constant := 31; 

fine delta : constant :=2 2.0 ** (-31); 
tick : constant := 1.0 / 18.2; 


—— Other System-Dependent Declarations 
subtype priority is integer range 1 .. 20; 
The value of system.memory_size is presently meaningless. 


F.5 Restrictions on Representation Clauses 


F.5.1 Length Clauses 


A size specification (t’ size) is rejected if fewer bits are specified than can accommodate the type. The 
minimum size of a composite type may be subject to application of pragma pack. It is permitted to specify 
precise sizes for unsigned integer ranges, e.g. 8 for the range 0. .255. However, because of requirements 
imposed by the Ada language definition, a full 32-bit range of unsigned values, i.e.0. . (2**32) —1, cannot 
be defined, even using a size specification. 

The specification of collection size (t’' storage_size) is evaluated at runtime when the scope of the type 
to which the length clause applies is entered, and is therefore subject to rejection (via storage_error) 
based on available storage at the time the allocation is made. A collection may include storage used for run— 
time administration of the collection, and therefore should not be expected to accommodate a specific number 
of objects. Furthermore, certain classes of objects such as unconstrained discriminant array components of 
records may be allocated outside a given collection, so a collection may accommodate more objects than 
might be expected. 

The specification of storage for a task activation (t’ storage_size) is evaluated at run-time when 
a task to which the length clause applies is activated, and is therefore subject to rejection (via storage_er- 
ror) based on available storage at the time the allocation is made. Storage reserved for a task activation is 
separate from storage needed for any collections defined within a task body. 


The specification of small fora fixed point type (t ’ sma11) is subject only to restrictions defined in the LRM 
section 13.2. 


F.5.2 Enumeration Representation Clauses 


The intemal code for the literal of an enumeration type named in an enumeration representation clause must 
be in the range of standard. integer. 


The value of an internal code may be obtained by applying an appropriate instantiation of un- 
checked_conversion to an integer type. 


F.5.3 Record Representation Clauses 
The storage unit offset (the at static_simple_expression part) is given in terms of 8-bit storage units and must 


be even. 
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A bit position (the range part) applied to adiscrete type component may be inthe range 0 « .15, withO being 
the least significant bit of a component. Arange specification may not specify a size smaller than can accom 
modate the component. a ComPONE™ cation for a component not accommodating bit packing "AY Toke 


Components of discrete types for which bit positions are specified may not straddle 16-bit word boundaries. 


The value of an alignment clause (the optional at mod part) must vale 19 1, 2, 4, or 8, and may not be 
smaller than the highest alignment required by any component of the record. On PC_-DOS, this means that 
some records may not have alignment clauses smaller than 2. 


F5.4 Address Clauses 


An address clause may be supplied for an object (whether constant or variable) or a task entry, but not fora 
, package, ortask unit. ‘The meaning of an address clause supplied for a task entry is given in °°" 
tion F.5.5. 


An address expression for an object is a 32-bit segmented memory address of type system. address. 
F5.5 Interrupts 


A task entry's address clause can be used to associate the entry with a PC- DOS SPL Values in the range 
0. .255 are meaningful, and represent the interrupts corresponding to those values. 


An interrupt entry may not have any parameters. 

F5.6 Change of Representation 

There are no restrictions for changes of representation effected by means of type conversion. 

F.6 Implementation-Dependent Components 

No names are generated by the implementation to denote implementation-dependent components. 
F7 Unchecked Conversions 


‘There are no restrictions on the use of unchecked_conversion. Conversions between objects whose 
sizes do not conform may result in storage areas with undefined values. 


F8 Input-Output Packages 


A summary of the implementation-dependent input-output characteristics is: 


e Incallsto open and create, the form parameter must be the empty string (the de- 
fault value). 


e More than one internal file can be associated with a single external file for reading 
only. For writing, only.one internal file may be associated with an extemal file; Do 
not use reset to get around this rule. 


e Temporary sequential and direct files are given names. Temporary files are deleted 
when they are closed. 


e File I/O is buffered; text files associated with terminal devices are line—buffered. 
e Thepackages sequential_ioand direct _iocannot be instantiated with un- 


constrained composite types or record types with discriminants without defaults. 
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F.9. Source Line and Identifier Lengths 
Source lines and identifiers in Ada source programs are presently limited to 200 characters in length. “sy 
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asm files, 150 

aatr files, 150 

err files, 150 

ext, 18 

_gnn files, 150 

int files, 38, 150 

Ast files, 150 

obj files, 150 

sep files, 150 
*constrained, 99 
“locoffset, 115, 199 
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& (catenation operator), 9 
&, function, 138 
$S$DATA (segment), 107 


~a auxiliary—directory\, 187 
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auglib, 167 
rmlib, 195 


-c, auglib, 167 


—c compiler-program—name 
amake, 164 . 


bamp, 171 
mklib, 187 


-d 
auglib, 168 
modlib, 189 


~d unit, Islib, 181 
~-¢, auglib, 168 
-f, bamp, 171 
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-f flags, amake, 165 
-£D, ada, 147 

-fF, ada, 147 

—fe, ada, 147 

fF, ada, 47, 147 
-fL, ada, 148 

-{N, ada, 148 

-fR, ada, 148 

-fS, ada, 82, 148 
-fs, ada, 148 

-fU, ada, 149, 154 
—fv, ada, 149 

fw, ada, 149 

-G, bamp, 37, 172 


-~g 
ada, 149 
bamp, 172 


-h, Islib, 181 

-I, bamp, 32, 172 
-i, bamp, 172 

-K, ada, 37, 38, 149 
-k, Islib, 181 


-l 
Islib, 153, 182 
modlib, 189. 


-L 
ada, 149 
amake, 165 
augiib, 168 
bamp, 172 
Inlib, 179 
Islib, 182 
mklib, 187 
modlib, 189 
mnlib, 195 
~-1 modifiers 
ada, 149 
modifiers, 151 
ec, 151 
p, 151 
s, 151 
t,151 
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-M, bamp, 91 
—m, bamp, 172 

-M main-program-stack-size, bamp, 172 
-M makefile, amake, 165 

-N, bamp, 172 

—n 


amake, 165 
bamp, 172 


—n string, modlib, 189 
—0, Islib, 182 
0 output-file-name, bamp, 172 
-P, bamp, 173 
-r 
auglib, 168 
bamp, 173 
mnlib, 195 
—t library—name (replacement-lib-name], Inlib, 179 
-S, ada, 149, 153 
—8, specifying stack size, 35 
~S task-stack-size, bamp, 173 
-t, Islib, 182 


~U 
bamp, 47—48, 173 
modlib, 189 


-v 


bamp, 173 
mnlib, 195 


-V scratch-file, bamp, 173 
—W, bamp, 173 

-w unit, Islib, 182 

-x, bamp, 82, 174 
/mustshare switch, 85 
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80286 instructions, generating, 148 


80x86 memory and Meridian Ada programs, 89—-90 
code size, 89 
global data size, 89 
heap storage, 90 
individual data object size, 90 
stack size, 89—90 
storage collections, 90—92 
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access denied, 24 
access object, 25, 102 
access to task, 102 
access type, constraint clash, 15 
access types, 102 , 


ada (Meridian Ada command), 147—156 
assembly code, producing, 153—154 — 
compiler output files, 150 
default option description file, 152—153 
description, 147 


options, 147—149 
—fD, 147 
—fE, 147 
-fe, 147 
-fF, 47, 147 
-{L, 148 
-£N, 148 
-fR, 148—149 
-fS, 82, 148 
fs, 148 
-fU, 149 
-fv, 149 
-fw, 149 
~g, 149 
-K, 37, 38, 149 
-L library modifiers, 149 
-1 modifiers, 149 
-S, 149, 153 


ada.aux, 191 
ada ini file, 152 
ada.lib, 191 


ada_io, package, 14, 120122 
ada2 
description, 157 
examples, 157 
invocation, 157 
adaext, 159 
description, 159 
extended mode, 83 
invocation, 159 
adareal, 161 
description, 161 
invocation, 161 


address clauses, 103—104, 201 

alignment holes, 101 

alignments, 102 

allocators, 89 

alternate compiler, 164, 171 

alternate executable file output name, 172 

alternate library, using, 149, 165, 172, 179, 182, 189 


array element arrangements, 98 
array types, 96—99 

constrained, 96 

dynamic, 96 

packed, 97-98 

unconstrained, 97 
array _object, package, description, 125—126 
array_type, package, description, 126—128 
arrays, large, 91 
arrays, limit to size of, 90 
ASCII DEL character, 153 
assembly code, producing, 149, 153—154 
assembly language interface, 105, 107—109, 197198 
assembly language listing, annotating, 147 
assignment would change discriminant, 14 
at, 73 
at mod part, 201 
at part, 200 
atan, function, 133 
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augment information, removing, 168 
augmented link information, 167—170 
automatic checks, troubleshooting, 14 
iliary di ‘es 
creating, 191 
description, 44 
naming, 187 


bamp, 171—176 
description, 171 
examples, 174—176 
invocation, 171 
linking programs to SFPRT, 47—48 
imization of code, 37 


—g, 172 

-I, 32, 172 

-i, 172 

~-L library-name, 172 
-M, 91 

—m, 172 

-M main-program-stack-size, 172 
-N, 172 

-n, 172 

-o output-file-name, 172 
-P, 173 

-, 173 
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-s task~stack—size, 173 

-u, 47-—48, 173 

-v, 173 

-V scratch-file, 173 

-W, 173 

—x, 82, 174 
specifying stack size, 35,91 
6 


benchmarking the compiler, 148 
bind command, 83 


bit_ops, package, 128—131 
function and, 129 
function not, 130 
function or,129 
function shi, 130—131 
function shr, 131 
function xor, 129-130 


7 by discrete types, 93 

used by real types, 94 
bodies, separating from specifications, 8 
body information, removing, 195 
Boolean, alignment of, 102—103 
Boolean, type, 93 
bottom margin, 152 
bottom_margin, 152 
breakp, 73 
buffering considerations, 21 
builtin language interface, 105, 197—198 
byte_array, type, 94 
byte_integer, type, 93, 199 


Cc 


¢ (debugger command), 73 
c language interface, 197-198 
calendar, package, 117 
calling conventions 
interface languages, 105—107 
Microsoft C language, 109-113 
case in symbol names, 105 
catenation and storage reclamation, 9 
character, alignment of, 102 
character, type, 93 
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clock, package, 168, 169 

close, procedure, 18—22 

closing files, 18, 22 


code model compatibility, with pragma interface, 107, 


109 


code size for 80x86 processor architecture, 89 


command format, 145 
command line options, using, 6 
command_word_type, 100, 101 
Meridian Ada 

ada, 147—156 

ada2, 157—158 

adaext, 159—160 

adareal, 161—162 

amake, 163—166 

auglib, 167~-170 

bamp, 171—176 

help, 177—178 

Inlib, 179—180 

Islib, 181—186 

mklib, 187—188 

modlib, 189—190 

newlib, 191—192 

ramp, 83, 193—-194 

mnlib, 195 
compilation unit entries, deleting, 195 
compilation unit names, reserved, 7—10 
compile verbosely, 149 
compiler 

benchmarking, 148 

increasing capacity, 82 

invoking, 147—-156 

output files, 150 
compiler error message, 151 
compiler won't run, 11—-12 
compiler, invoking, 6 
compiler/library interaction, 40 
constrained array objects, 96 
constraint_error exception, 15 
context clause, 41 
continuous listing, 151 
controlled, pragma, 197 
cos, function, 132 
count, function, 123—124 
count, type, 26, 94 


data object size, 90 

data representations, internal, 93-—104 
data transformations, 110—113 

data, function, 124—125 

data_error exception, 15, 23 

date, including in header, 153 


default file name components, 19 
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default option description file, 152—153 
default program library, creating, 191—192 
DEL character, 153 


direct_int_io, 41 

direct_io, package, 24—25, 41, 117, 201 
disabling floating point checks, 47 
discrete types; 93 

discriminant array components, 99 
discriminant clash, 15 
discriminant record, 99 

disjoint libraries, 44 

dispose, procedure, 91—92 

divide by zero, 15 

dump, 74 

dumpall, 74 

dynamic array objects, 96 


E 


elaborate, pragma, 197 

elements of an array, 98 

empty, function, 137 

end_error exception, 15 

end_of_page, function, 22 

enumeration representation clauses, 94—-96, 200 
enumeration type, 93 

exror log file, generating, 147 

exror message character string, 152 


error messages. 

cannot exec to pathiadal.exe, 11 

exception never handled, 14—16 

form, 150—151 

main program xxx xxx is not in the library, 13 

missing library unit x, 13 

must install math coprocessor to use Host persons 


oaine cannot find operating system kernel, 13 
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wrong version in library, 14 
exror_tag, 152 
excbreak, 74 
exception location information, emitting, 148 
exception never handled, 14—16 
exceptions, 23 
execute, 75 
exp, function, 132 
expanded memory, 82 


extended mode, 3184 
adaext, 83 
address clauses, 103-104 


FAR PROC, 107 

file contents, listing, 151 
file does not exist, 24 
file forms, 21 
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files 

deleting, 46 

moving, 46 
find, 75 
fio, package, 14, 119 
fixed point representations, 94 
floating point checks, disabling, 47, 147 
floating point constraint clash, 15 
floating point divide by zero, 15 
floating point libraries, linking with bamp, 173 
floating point representations, 94 
floating point software, 47—48 
floating point value out of range, 15 
form file, keeping, 149 
form, function, 23 
format control, listing, 151 
format, file name, 18—21 
function 

&, 138—139 

and, 129 

atan, 133 

cos, 132 

count, 123-124 


data, 124—125 
empty, 137—138 


" end_of_page, 22 


iio, package, 14, 119-—122 
illegal form, 24 

illegal name, 24 

illegal record variant, 15 
illegal reset mode, 24 
implementation defined types, 26 
implementation—dependent components, 201 
implemented pragmas, 197 
inlining, 171 

input-output of text, 141 
input-output packages, 201 
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Input/Output, 17—26 
instantiation of text_jo.integer_io, 119—122 
insufficient memory, 23 
imeger size, 8 
integer, standard., 200 
integer, type, 93 
imegers, reading and writing, 119—122 
Intel linker, 107 
interface to assembly language, 107—109 
interface, pragma, 105—116, 197-—198 
calling conventions, 105—107 
code model compatibility, 107 
code model compatibility for Microsoft C, 109 
data transformations, 110—113 
description, 105 
example using auglib, 168—170 
form, 105 
interface to assembly language, 107—109 
interface to Microsoft C, 109—113 
linking Meridian Ada programs with Microsoft C, 


machine code insertions, 114—115 
Meridian—Pascal, 113—114 
Microsoft C calling conventions, 109 
Object code compatibility, 107 
object code compatibility for Microsoft C, 109 
register usage, 107 
stack frames, 106 

internal data representations, 93——104 
access types, 102 
address clauses, 103 
alignment holes, 101—103 


discrete types, 93—94 
discriminant array components, 99 
dynamic array objects, 96 


internal documentation string, changing, 189 
internal error, 23 
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internal language interface, 105, 197—198 
intemal library name, changing, 189 
interrupt entries, 35 . 
imerrupts, 46, 201 

invalid data, 23 

io_exceptions, 117 


kernel, unable to locate, 13 


large arrays, 91 

layout_error exception, 15 

leaving files open, 21 

left margin, specifying, 153 

left_margin, 153 

length clash in multi-dimensional array, 15 
length clauses, 200 

length or discriminant clash, 15 

length, function, 137 


library graph, listing, 181 
library links, 41 
library management 
library database, 39 

library integrity, 46 

library links, 41 

naming Ada identifiers, 44 

using newlib, 39 

using rmlib, 46 
library memory, 39—46 
library references, adding, 179 
library sub-tree, listing, 181 
library unit entry, removing, 195—196 
library units, missing, 13 
library update, inhibiting, 149 
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Library updated field, 86 
LIM, 82 
lineno_width, 153 
lines per page, 153 
lines, number of in botiom margin, 152 
link entries, listing, 181 
link map, producing, 172 
link names, alphabetic case of, 105 
link program libraries, 179-—180 
link syntax 
connected, 167 
detached, 168 
link-name parameter, 105 
link-parameter information, inserting, 167, 168 
linkage, stopping, 165 
linker, invoking, 6 
linking libraries, 41 
linking Meridian Ada programs with Microsoft C, 113 
list, 76 : 
list, pragma, 151, 197 
listing file contents, 151 
listing file, generating, 149 
listing format control, 151 
listings, producing, 151—152 
In, function, 133 


Inlib, 40, 179—180 
-L library-name, 179 
—t library-name [replacement-lib-name], 179 
description, 179 


locate, function, 141 
locking a library, 189 
long—format listing, 182 
long_integer, type, 93, 199 
Lotus—Intel-Microsoft (LIM); 82 
low level I/O, 23 
Islib, 39, 181 

description, 181 

examples, 182—186 

invocation, 181 

options, 181—182 

~A, 181 


machine code insertions, 108, 114—115 
machine_code, 114 
main program generation, suppressing, 171 
makefile, selecting alternative, 165 
margin 

bottom, 152 


left, 153 
top, 153 


marker_lines, 153 
math co-processor, 148 
math co—processors, running without, 47 


math_lib, package, 131—133 
function atan, 133 


memory, compiler out of, 12-13 

memory, program running out of 90 

memory_size, pragma, 197 

Meridian Ada optimizer, 37—38 

Meridian Ada Utility Library. See utility library, Me- 
ridian Ada 

Meridian Internal Form (MIF) library unit, 38 

Meridian object modules, 107 

Meridian-Pascal, 113—114 


Microsoft 
object module format, 107 
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object modules, 107 


mklib, 6,40, 187—188 
description, 187 


-c compiler—program—name, 187 
-L library-name, 187 


mod, 102 
mode_error exception, 15 
modlib, 189—190 
description, 189—190 
invocation, 189—190 
options, 189—-190 
-d, 189 
-i, 189 
-L library modifiers, 189 
-n string, 189 
-u, 189 
with Groupware, 86 
money’small, 94 
more, 76 
moving files, 46 
ms options, 85 
multidimensional array, length clash, 15 
must install math coprocessor fo use float operations, 
47 


mustshare switch, 85 


N 


name, illegal, 24 
name_error exception, 15, 24 
net use command, 85 
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null access value, reference through, 15 
number of open files, 21 


numeric checks, suppressing, 148 
numeric_ error exception, 15 


Oo 


object code compatibility, with pragma interface, 107, 
109 


object file linkage, suppressing, 172 
objects, unconstrained, 24—25 
open files, number of, 21 

open, procedure, 18—22, 201 
opening files, 18, 21 

operator &, 9 

optimization, specifying, 149, 172 
optimize, pragma, 197 

Optimizer, using, 37—38 

option description file, 152—-153 
or, function, 129 

OS/x86: cannot find operating system kernel, 13 
out of memory, 90 

output file name, alternate, 172 
output files, 150 


p 


pack, pragma, 96, 198—199 


ada_io, 14, 120—122 

arg. See arg, package 
array_object, 125-—126 
aray_type, 126—128 
bit_ops. See bit_ops, package 
calendar, 117 
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clock, 168, 169 

direct_int_io, 41 

direct_io, 24—25, 41, 117, 201 

fio, 14, 119 

iio, 14, 119—-122 

io_exceptions, 117 

machine code, 114 

math_lib. See math_lib, package 
reset, 201 

sequential_io, 24A—25, 117, 201 

spio, 133—134 

spy. See spy, package 

standard, 117 

system, 199—200 

task_control, 32—34 

text_handler. See text_handler, package 
text_io, 117, 120 
unchecked_conversion, 117, 200, 201 
unchecked_deallocation, 117 


packed arrays, 97 
packed records, 100 
page eject, 20, 153 
page, pragma, 151, 197 
page_length, 153 
page_width, 153 

peek, function, 135 
poke, procedure, 135 
portability, 8 


pragma 
controlled, 197 
elaborate, 197 
interface. See interface, pragma 
list, 151, 197 
memory_size, 197 
optimize, 197 
pack, 96, 198—199 
page, 151, 197 
priority, 29, 197 
shared, 35,197. 
storage_unit, 197 
suppress, 197, 199 
system_name, 197 
pragmas, implemented, 197 
pre_emption_off, procedure, 33 


pre_emption_on, procedure, 33 


212 


sepper,95 
task_control.set-time_slice, 33 
program guidelines, 5 
program library 
adding links, 179—180 
creating default, 191—192 
listing, 181—186 
program library, creating, 5 
program optimization, 37—38 
program size, reducing, 8 
program_error exception, 15 
containing floating point computations, 47 
creating to run in mode, 82 
running in extended mode, 83 


ramp, 193—194 
description, 193 
examples, 193—194 
extended mode, 83 
files used by, 193 
invocation, 193 
range for option description entry, 152—153 
raw, 77 
raw mode, 72 


re-linkable output, creating, 173 


Index 


reading integers with package iio, 119—122 
real mode programs, description, 7 

real types, 94 

record representation clauses, 200 

record representation specifications, 100—101 
record types, 99102 

record variant, illegal, 15 

reducing program size, 8 

register usage, 107 

relational functions, 139 

replace link, 179 


rpc.lockd daemon, 85 

run time performance in extended mode, 84 
run-time memory usage, 89—90 

running extended mode programs, 83 
runtime_names, 116 

runtime_names, pragma, 116 


separating specifications and bodies, 8 
sequential_io, package, 2A—25, 117, 201 
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set subprogram, 125 
Set, procedure, 139 
set_input, 7 
set_output, 77 
set_time, procedure, 168 
settaskname, 77 

shared, pragma, 35, 197 
shi, function, 130 
short_integer, type, 199 
shr, function, 131 
silence, 78 

sin, function, 132 
small_range, subtype, 93 


Software Floating Point Run-Time (SFPRT), 47—48 


source, 78 

source code, entering, 5 
source line lengths, 202 
specifications and bodies, separating, 8 
spio, package, 133—134 


stack size, specifying, 91, 172 
stack size, specifying, 35 


standard packages, 117 
calendar, 117 
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standard, package, 117 
standard_input, 17 

standard_output, 17 

static initialization of variable, inhibiting, 148 
status_error exception, 15 

stepper, procedure, 95 

storage collections, 90 

storage reclamation, 9 

storage, pragma, 197 

storage_error exception, 15, 91—92 
summary, 153 

suppress, pragma, 197, 199—200 


task entry address clauses, 104 

task stack size, specifying, 173 

task, access to, 102 
task_control.set_time_slice, procedure, 33 
task_control, package, 32—34 


controlling at run-time, 32 


terminal I/O, 17 
terminal input and output, 120—122 
terminators, 22 
text_handler, package, 136—142 
function &, 138—139 
function empty, 137—138 
function length, 137 
function locate, 141 
function to_text, 138 
function value, 137 
input-output of text, 141 
amend, 140—141 
procedure append, 140 
procedure set, 139-—140 
relational functions, 139 
text_io.float_io, instantiating, 119 
text_io.integer_io, 119 
text_io, package, 117, 120 
time order, listing in reverse, 182 


byte_array, 94 
byte_integer, 93, 199 
character, 93 
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command_word_type, 100, 101 


unbreakp, 79 
unchecked _conversion, package, 117, 200, 201 
unchecked_deallocation, package, 90, 117 
unconstrained array access object, 102 
unconstrained array objects, 97 
unconstrained objects, 24—25 
unit type, listing, 182 
unlocking the library, 189 
unresolved symbols, 154 
untrace, 80 
untraceall, 80 
unwatch, 80 
use_error exception, 15, 24 
utility library, Meridian Ada, 123—142 
description, 4 
package arg, 123—125 
function count, 123124 
function data, 124—125 
package array_object, description, 125—126 
package array_type, description, 126—128 
package bit_ops, 128—131 
function and, 129 
function not, 130 
function or, 129 
function shi, 130—131 
_ function shr, 131 
function xor, 129—-130 
package math_lib, 131—133 
function atan, 133 
function cos, 132 
function exp, 132 
function In, 133 
function sin, 132 
function sqrt, 133 
package spio, 133—134 
package spy, 134—135 
function peek, 135 
procedure poke, 135 
text_handler, 136—142 
function &, 138—139 
function empty, 137—138 
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value out of range, 15 

value, function, 137 
verbosely, linking, 173 
virtual mode, link using, 173 
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